Swagger3

接口文档

产生

• 接口开发人员，即后端工程师

维护

• 接口开发人员，即后端工程师

使用

1. 前端人员
2. 测试人员
3. 产品经理

接口存在问题

1. 接口文档不存在，靠抓包获取
2. 接口更换后文档更新不及时
3. 接口文档写错，注解写错
4. 自动生成文档工具跨语言不兼容

OpenApi规范

OpenAPI规范（OAS）是一种通用的、和编程语言无关的API描述规范，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码、文档或针对接口进行嗅探。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。
OpenAPI始于Swagger规范，Swagger规范已于2015年捐赠给Linux基金会后改名为OpenAPI，并定义最新的规范为OpenAPI 3.0。

地址: https://github.com/OAI/OpenAPI-Specification

OpenAapi实现

OpenAPI v3（OAS 3）
Swagger v2

OpenApi核心部分

1. openapi - OpenAPI规范版本的语义版本号
2. info - 有关API的元数据
3. paths - API的可用路径和操作

自动化接口文档方案

方案一: ApiDoc

由javascript语言开发，依赖node。编程源代码中的注释直接自动生成API接口文档的工具。
地址: https://apidocjs.com/
GitHub: https://github.com/apidoc/apidoc

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

优点

1. 不侵入代码
2. 支持跨语言使用
3. 界面简介友好

缺点

依赖于node/npm环境
需要在注释中增加指定注解，如果代码参数或类型有修改，需要同步修改注解相关内容，有一定的维护工作量。swagger是在代码中加注解，而apidoc是在注解中加数据，代码嵌入性更小，比较推荐使用。

方案二: Swagger

在java代码里面增加注解生成接口文档。
地址: https://swagger.io/

优点

1. 支持SpringMVC、SpringBoot、SpringCloud等主流java框架.
2. 对java代码友好
3. 界面简洁
4. 国内比较活跃,主要是spring社区带动
5. 功能比较多

缺点

1. 对跨语言支持不友好(可以和knife4j整合解决这个问题)
2. 代码需要引入相关依赖包和配置
3. 文档相对较少

Swagger3.0

基于OpenAPI规范（OpenAPI Specification，OAS）构建的开源接口文档自动生成工具，可以让开发人员快速设计、构建、记录以及使用Rest API。

swagger主要部分

Swagger Editor: 基于浏览器的编辑器，可以使用它编写我们OpenAPI规范。
Swagger UI：将我们编写的OpenAPI规范呈现为交互式的API文档。
Swagger Codegen: 通过OpenAPI(即以前的Swagger)规范定义的任何API生成服务器存根和客户端SDK来简化构建过程。

SpringFox(spring社区维护的一个非官方项目)

是一个开源的APIDoc框架，是一个基于SPring的组件swagger-springmvc，用于将swagger集成到springmvc中来，它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现.官方定义为: Automated JSON API documentation API's built with Spring。
地址: https://github.com/springfox/springfox

SpringFox3.0

Spring5、Webflux支持,依赖少
支持OpenApi 3.0.3
有springboot的整合的starter，使用更便捷

SpringBoot2.X整合Swagger3.X

pom.xml引入依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

application.properties配置文件增加配置

# 中文会乱码，可以修改文件编码或者使用yml格式
spring.application.name=projectName

# ======= 自定义swagger配置 =======#
swagger.enable=true
swagger.application-name=${spring.application.name}
swagger.application-version=1.0
swagger.application-description=Api info

#swagger升级2.6x之后和springboot出现了不兼容情况
#spring.mvc.pathmatch.matching-strategy=ant_path_matcher

swagger3配置类

package com.swagger.config;

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @Data是lombok，可以自己写getter/setter
 * @ConfigurationProperties("swagger")是读取application.properties中swagger开头的配置
 */
@Component
@Data
@ConfigurationProperties("swagger")
@EnableOpenApi
public class SwaggerConfiguration {

    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量读取properties配置
     */
    private Boolean enable;
    /**
     * 项目应用名
     * 对应application.properties中的swagger.enable
     */
    private String applicationName;
    /**
     * 项目版本信息
     * 对应application.properties中的swagger.application-version
     */
    private String applicationVersion;
    /**
     * 项目描述信息
     * 对应application.properties中的swagger.application-description
     */
    private String applicationDescription;
    /**
     * 接口调试地址
     */
    private String tryHost;


    @Bean
    public Docket createRestApi() {
        //swagger设置，基本信息，要解析的接口及路径等
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")

                //是否开启swagger，false为关闭，可以通过变量控制，线上关闭
                .enable(enable)

                //配置api文档的元信息
                .apiInfo(apiInfo())

                //选择哪些接口作为swagger的doc发布
                .select()

                //RequestHandlerSelectors.any()  所有都暴露
                //RequestHandlerSelectors.basePackage("com.autumn.*")  指定包位置
                //设置通过什么方式定位需要自动生成文档的接口，这里定位方法上的@ApiOperation注解
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                //接口URI路径设置，any是全路径，也可以通过PathSelectors.regex()正则匹配
                .paths(PathSelectors.any())

                .build();
    }

    //生成接口信息，包括标题、联系人，联系方式等
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("autumn", "https://www.cnblogs.com/aeolian/", ""))
                .version(applicationVersion)
                .build();
    }
}

测试

访问http://localhost:8080/swagger-ui/index.html

使用swagger注解

import java.util.*;
import org.springframework.web.bind.annotation.*;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

@Api(tags = "用户模块",value = "用户Controller")
@RestController("/user")
public class userController {

    @GetMapping("/info")
    @ApiOperation("用户信息")
    public Map info(){
        Map result = new HashMap();
        result.put("name","Gloria");
        result.put("age",19);
        return result;
    }

    @PostMapping("/login")
    @ApiOperation("用户登录")
    public String login(
            @ApiParam(name = "phone",value = "手机号",example = "15388889597")
            @RequestParam("phone") String phone,
            @ApiParam(name = "pwd",value = "密码",example = "123456")
            @RequestParam("pwd") String pwd){
        return phone + " login success";
    }

}

类注解@Api

@Api模块配置，用在Controller类，描述API接口

@Api(tags = "用户模块",value = "用户Controller")
@RestController("/user")
public class userController {

}

方法注解@ApiOperation

@ApiOperation接口配置，用在方法上，描述接口方法

    @GetMapping("/info")
    @ApiOperation("用户信息")
    public Map info(){
        Map result = new HashMap();
        result.put("name","Gloria");
        result.put("age",19);
        return result;
    }

参数注解@ApiParam

@ApiParam方法参数配置，用在入参上面，描述参数

@ApiParam(name = "phone",value = "手机号",example = "15388889597")

忽略注解@ApiIgnore

@ApiIgnore忽略此接口不生成文档。

@ApiModel

用于类表示对类进行说明，用于参数用实体类接收，value表示对象名，description描述。
一般用在post创建的时候，使用对象提交这样的场景。

@ApiModelProperty

用于方法、字段；表示对model属性的说明或者数据操作更改
value： 字段说明
name： 重写属性名
dataType: 重写属性类型
required: 是否必填
example: 举例说明
hidden: 隐藏

注意事项

1. 明确http请求方式，一个接口用@RequestMapping会生成多个文档
2. 线上要关闭接口文档
3. 考虑当下和未来是否可以一直用

报错

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

#swagger升级2.6x之后和springboot出现了不兼容情况
spring.mvc.pathmatch.matching-strategy=ant_path_matcher