SpringBoot-Swagger

Swagger

目录

1. 简介

  • 号称世界上最流行的API框架
  • RestFul API 文档在线自动生成工具 => API文档与API定义同步更新
  • 直接运行, 可以在线测试API接口
  • 支持多种语言
  • 在项目中使用Swagger需要SpringFox
    • Swagger2
    • ui

2. SpringBoot集成Swagger

1. 导入依赖

Swagger3.0直接导入Springfox Boot Starter就可以了

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.X版本需要导入Swagger2.0和UI

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

我们这里还是使用2.X版本

2. 配置Swagger

package com.wang.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {
    
}

注意

  • 只要在Swagger配置类上加上@EnableSwagger2注解, 就可以使用Swagger2了
  • Swagger的地址为http://localhost:8080/swagger-ui.html

3. Swagger配置

1. 配置Swagger信息

Swagger的Bean实例 ==> Docket

package com.wang.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
//开启Swagger2
@EnableSwagger2
public class SwaggerConfig {

    //配置了Swagger的Docket的Bean实例
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息 apiInfo
    private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new Contact("wang", "https://www.cnblogs.com/wang-sky/", "715180879@qq.com");

        return new ApiInfo(
                "我的Swagger接口文档",
                "这是一个Swagger接口文档",
                "V 1.0",
                "https://www.cnblogs.com/wang-sky/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }


}

这里修改的是Swagger页面的一些信息, 结果如下

image-20200925141343307

注意

  • Docket不要忘了注册Bean并返回一个new Docket
  • 返回的Docket要传入一个参数指定产生的文档的类型, 我们这里使用 DocumentationType.SWAGGER_2

2. Swagger配置扫描接口

Docket.select()

@Bean
public Docket docket() {
    //RequestHandlerSelectors 配置要扫描接口的方式
    /*
    basePackage     指定要扫描的包
    any             扫描全部
    none            都不扫描
    withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 比如 withClassAnnotation(RestController.class)
    withMethodAnnotation    扫描方法上的注解
     */
    //paths 过滤的路径, 需要传入PathSelectors.xxx 选择过滤的方式
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
            .paths(PathSelectors.ant("/wang/**"))
            .build();
}

注意

  • apis 扫描, 要传入RequestHandlerSelectors.xxx 指定扫描的方式
    • basePackage 指定要扫描的包
    • any 扫描全部
    • none 都不扫描
    • withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 比如 withClassAnnotation(RestController.class)
    • withMethodAnnotation 扫描方法上的注解
  • paths 过滤的路径, 需要传入PathSelectors.xxx 选择过滤的方式
  • 最后要.build(), 建造者模式, 同时由于这是链式编程, 一定要写!
  • select().XXX.XXX...bulid()是一套, 中间可以写的方法是确定的, 不能乱写

3. 配置Swagger是否启动

只在生产环境下使用Swagger, 而在发布的时候不使用的方法

分别建立不同环境的yml

image-20200925150147345

在application中选择启动的环境, 这里选择生产环境

spring:
  profiles:
    active: dev

配置Swagger

//配置了Swagger的Docket的Bean实例
@Bean
public Docket docket(Environment environment) {
    //RequestHandlerSelectors 配置要扫描接口的方式
    /*
    basePackage     指定要扫描的包
    any             扫描全部
    none            都不扫描
    withClassAnnotation 扫描类上的注解,参数是一个注解的反射对象, 比如 withClassAnnotation(RestController.class)
    withMethodAnnotation    扫描方法上的注解
     */
    //paths 过滤的路径, 需要传入PathSelectors.xxx 选择过滤的方式

    //设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");

    //通过environment.acceptsProfiles, 判断是否处在自己设定的环境当中
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
            .paths(PathSelectors.ant("/wang/**"))
            .build()
            .enable(flag);
}

注意

  • .enable
  • 只能在select().XXX.XXX....bulid() 外面写
  • 默认为true, 如果为False, 则Swagger不能在浏览器中访问
  • 要用 Profiles profiles = Profiles.of("dev"); 指定激活的环境的名字
  • 获得当前的生产环境(application指定的环境), 要给Docket传入一个Environment对象, 其中保存了当前环境的名字
  • environment.acceptsProfiles(profiles); 利用此方法获得是否在给定环境的布尔值

4. 配置API文档的分组

.groupName("我的API")

配置多个分组, 只需要配置多个Docket即可

4. 实体类配置

1. 实体类的注解

package com.wang.pojo;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
//@Api("注释")
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
}

@ApiModel或者@Api在类上

@ApiModelProperty在属性上

属性为私有, 要写getter才能取到属性名

结果显示在Model上

image-20200925162237381

2. 接口类的注解

package com.wang.controller;

import com.wang.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping(value = "/hello")
    public String hello() {
        return "Hello!";
    }

    //只要我们的接口中, 返回值中存在实体类, 他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    //Operation接口
    //Get请求中, 如果添加了字段的注释@ApiParam, Swagger无法测试
    @ApiOperation("Hello2接口")
    @GetMapping("/hello2")
    public String hello2(String username) {
        return "hello " + username;
    }

    //Operation接口
    @ApiOperation("Hello3接口")
    @PostMapping("/hello3")
    public User hello3(@ApiParam("用户") User user) {
        return user;
    }
}

注意

  • 只要我们的接口中, 返回值中存在实体类或者字符串, 他就会被扫描到Swagger中
  • @ApiOperation 方法的注释
  • @ApiParm 参数的注释
  • Get请求中, 如果添加了字段的注释@ApiParam, Swagger无法测试

5. 总结

  • 我们可以通过Swagger给一些比较难理解的属性或者接口, 增加注释信息
  • 接口文档实时更新
  • 可以在线测试
  • 注意, 在正式发布的时候, 关闭Swagger(出于安全考虑, 而且节省运行内存)
【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/wang-sky/p/13731068.html