Swagger3
接口文档
产生
- 接口开发人员，即后端工程师
维护
- 接口开发人员，即后端工程师
使用
- 前端人员
- 测试人员
- 产品经理
接口存在问题
- 接口文档不存在，靠抓包获取
- 接口更换后文档更新不及时
- 接口文档写错，注解写错
- 自动生成文档工具跨语言不兼容
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核心部分
- openapi - OpenAPI规范版本的语义版本号
- info - 有关API的元数据
- 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.
*/
优点
- 不侵入代码
- 支持跨语言使用
- 界面简介友好
缺点
依赖于node/npm环境
需要在注释中增加指定注解，如果代码参数或类型有修改，需要同步修改注解相关内容，有一定的维护工作量。swagger是在代码中加注解，而apidoc是在注解中加数据，代码嵌入性更小，比较推荐使用。
方案二: Swagger
在java代码里面增加注解生成接口文档。
地址: https://swagger.io/
优点
- 支持SpringMVC、SpringBoot、SpringCloud等主流java框架.
- 对java代码友好
- 界面简洁
- 国内比较活跃,主要是spring社区带动
- 功能比较多
缺点
- 对跨语言支持不友好(可以和knife4j整合解决这个问题)
- 代码需要引入相关依赖包和配置
- 文档相对较少
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: 隐藏
注意事项
- 明确http请求方式，一个接口用@RequestMapping会生成多个文档
- 线上要关闭接口文档
- 考虑当下和未来是否可以一直用
报错
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
#swagger升级2.6x之后和springboot出现了不兼容情况
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
