Swagger

无论是前端还是后端开发，都或多或少被接口文档折磨过。前端抱怨接口文档更新不及时，与实际接口有出入。后端又是那句经典：最讨厌别人的代码不写注释，最讨厌自己的代码要写注释。写文档亦是如此。随着版本迭代，文档跟不上代码也是必然的了。所以这时候Swagger出现了……

1. SpringBoot 集成 Swagger

新建一个SpringBoot - web项目

导入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- 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>

编写一个Hello工程

配置SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
}

测试运行 http://localhost:8080/swagger-ui/index.html

2. 配置Swagger基本信息

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

// 配置Swagger信息 apiInfo
private ApiInfo apiInfo() {
    // 作者信息
    Contact contact = new Contact("123", "http://cimoc.cn", "1104738025@qq.com");
    return new ApiInfo(
        "Swagger Api文档",
        "Api文档描述",
        "1.0",
        "http://localhost",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList());
}

3. Swagger配置扫描接口

// 配置了Swagger的Docket的bean实例
@Bean
public Docket docket(Environment environment) {
    // 设置要显示的Swagger环境
    Profiles profiles = Profiles.of("dev");
    // 通过environment.acceptsProfiles判断是否处在这个环境
    boolean flag = environment.acceptsProfiles(profiles);
    
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        // enable 是否启动Swagger
        .enable(false)
        .select()
        // RequestHandlerSelectors配置要扫描接口的方式
        // basePackage指定要扫描的包
        // any() 扫描全部
        // none() 不扫描
        // withClassAnnotation 扫描类上的注解
        // withMethodAnnotation 扫描方法上的注解
        .apis(RequestHandlerSelectors.basePackage("com.lgz.swagger.controller"))
        // paths() 过滤路径
        .paths(PathSelectors.ant("/**"))
        .build();
}

4. Swagger扫描实体类

只要我们的接口返回中存在实体类，swagger就会扫描

@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

@ApiOperation("用户方法")
@PostMapping("/user")
public User user(@ApiParam("用户参数")@RequestBody User user) {
    return user;
}

5. 常用注解

@Api 用于类
用来描述一个控制器
@Api(value="User Controller",tags={"用户操作接口"})
@ApiOperation 用于方法
用来描述接口方法
@ApiOperation(value = "用户登录", notes = "方法提示")
@ApiModel 用于类
用来描述实体类
@ApiModel(value = "FeedbackInputDTO", description = "反馈提交参数")
@ApiModelProperty 用于方法和属性
用来描述实体类的字段
@ApiModelProperty("反馈类型")
@ApiIgnore 用于类，方法，和方法参数
用来忽略方法或类或参数