[Java知识库]SpringBoot集成Swagger2自动生成API接口文档

一、导入依赖

<!-- Swagger的注解依赖包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
        <!-- Swagger接口文档页面包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

二、配置类

package com.example.swagger2.config;

import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @author feimao
 * @date 2022-03-30
 */
@Configuration
@EnableSwagger2
public class Swagger2Config extends WebMvcConfigurationSupport {

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 是否启用Swagger（可写到配置文件application.yml中）
                .enable(true)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.example.swagger2"))
                // 扫描所有 .apis(RequestHandlerSelectors.any())
                //为任何接口生成API文档
                .paths(PathSelectors.any())
                .build()
                /* 设置安全模式，swagger可以设置访问token */
                //.securitySchemes(securitySchemes())
                //.securityContexts(securityContexts())
                // 统一请求前缀（可写到配置文件application.yml中）
                .pathMapping("/dev-api");
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    //private List<SecurityScheme> securitySchemes() {
    //    List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
    //    apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
    //    return apiKeyList;
    //}

    /**
     * 安全上下文
     */
    //private List<SecurityContext> securityContexts() {
    //    List<SecurityContext> securityContexts = new ArrayList<>();
    //    securityContexts.add(
    //            SecurityContext.builder()
    //                    .securityReferences(defaultAuth())
    //                    .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
    //                    .build());
    //    return securityContexts;
    //}

    /**
     * 默认的安全上引用
     */
    //private List<SecurityReference> defaultAuth() {
    //    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    //    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    //    authorizationScopes[0] = authorizationScope;
    //    List<SecurityReference> securityReferences = new ArrayList<>();
    //    securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
    //    return securityReferences;
    //}

    /**
     * 配置swagger2的静态资源路径
     *
     * @param registry
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：xx管理系统_接口文档")
                // 描述
                .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                // 作者信息
                .contact(new Contact("feimao", "http://项目地址、公司官网.com", "123@163.com"))
                // 版本
                .version("版本号:1.0")
                .build();
    }

    /**
     * 创建一个分组（可选，创建分组后会在界面右上角切换）
     * @return
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("肥猫的分组")
                // 配置分组详情
                .apiInfo(apiInfo());
    }
}

三、Swagger2注解详解

1、@Api ：请求类的说明

@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
    tags="说明该类的作用"
    value="该参数没什么意义，所以不需要配置"

举例：

@Api(tags = "账户相关模块")
@RestController
@RequestMapping("/api/account")
public class AccountController {
    //TODO
}

3、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明      
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）     
        dataType：参数类型，默认String，其它值dataType="int"       
        defaultValue：参数的默认值

举例：

@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
        @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
        @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
        @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public AjaxResult login(@RequestParam String mobile, @RequestParam String password,
                        @RequestParam Integer age){
    //TODO
    return AjaxResult.OK();
}

单个参数举例

@ApiOperation("根据部门Id删除")
@ApiImplicitParam(name="depId",value="部门id",required=true,paramType="query")
@GetMapping("/delete")
public AjaxResult delete(String depId) {
    //TODO
}

4、@ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
    @ApiResponse：每个参数的说明
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

举例：

@ApiOperation(value = "修改密码", notes = "方法的备注说明，如果有可以写在这里")
@ApiResponses({
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径找不到")
})
@PostMapping("/changepass")
public AjaxResult changePassword(@AutosetParam SessionInfo sessionInfo,
        @RequestBody @Valid PasswordModel passwordModel) {
    //TODO
}

5、@ApiModel：用于JavaBean上面，表示一个JavaBean

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
    （这种一般用在post创建的时候，使用 @RequestBody 这样的场景，请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

6. @ApiModelProperty：用在JavaBean的属性上面，说明属性的含义

@ApiModel和 @ApiModelProperty举例：

@ApiModel("修改密码所需参数封装类")
public class PasswordModel
{
    @ApiModelProperty("账户Id")
    private String accountId;
//TODO
}

总结：API文档浏览地址

配置好Swagger2并适当添加注解后，启动SpringBoot应用，
访问http://localhost:8080/swagger-ui.html 即可浏览API文档。
另外，我们需要为了API文档的可读性，适当的使用以上几种注解就可以。

四、把Swagger2的API接口导入ApiPost（postman同理）

1、访问http://ip:端口/swagger-ui.html 文档的首页，复制下面这个地址，浏览器打开后，直接Ctrl+S 保存json文件到电脑

2.打开ApiPost