没有required_springboot-使用OpenAPI之后我再也没有写过接口文档

一前言

这篇文章主要是带大家入门下如何使用OpenAPI, 笔者在github上找到对应得swagger项目都没找到javase得人门文章，看了下是基于JAX-RS，吐血了；

二什么是 OpenAPI，

OpenAPI 是一种基于Resful 风格对 API进行格式化描述的一种规范；允许你描述你整个项目的API，简单的讲就是一种接口文档生成的规范；包括如下几点：

端点描述（如 GET /user , Post /user）;
操作的参数，入输入参数，输出参数；
认证信息
联系信息，许可条款，声明等

OpenAPI 3.0 Specification

三什么是 Swagger

Swagger 由多个组件组成，它是一个开源的构建工具，其作用就是以 OpenAPI 为规范基准，能够帮助开发人员设计，构建文档，测试接口，文档规范化，和消费掉Restful API；说白了就是 OpenAPI 的实现，能够生成接口文档，以后不用自己手写了！！！我们可以看下其主要组件如下：

Swagger Editor 是一个编辑工具，可以编辑描述API；
Swagger UI 能让OpenAPI呈现出规范的可交互的API文档，以供他人查阅；
Swagger Codegen 基于OpenAPI规范能够生成客户端类库，服务端文档和存根，并且支持多语言，支持使用Docker,jar等方式运行构建；

更多组件详细看官网：swagger doc，看了官网的ylm格式基本结构晕，一堆黑的，客户体验非常不友好吐槽一下！看了github是基于JAX-RS 应用，不是很懂，再吐槽一下；

四 API生成

4.1 相关注释

4.2 pom.xml

<dependencies><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-annotations</artifactId><version>1.5.22</version></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.22</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.16.18</version><optional>true</optional></dependency></dependencies>

4.3 swagger配置

主要是配置一些项目得基本信息，注解路径，项目主要联系人等；比较重要是@EnableSwagger2表示开启Swagger；

/*** @Author lsc* <p> swagger 配置 </p>*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {// 构建文档Docket docket = new Docket(DocumentationType.SWAGGER_2);// 文档信息Docket build = docket.apiInfo(apiInfo())// 查询.select()// 注解包的路径.apis(RequestHandlerSelectors.basePackage("com.zszxz.swagger.controller"))// 任何路径.paths(PathSelectors.any()).build();return build;}/* ** @Author lsc* <p> 文档信息</p>* @Param []* @Return springfox.documentation.service.ApiInfo*/private ApiInfo apiInfo() {// 文档对象构建器ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();// 文档标题ApiInfo apiInfo = apiInfoBuilder.title("知识追寻者（公众号） API doc")// 描述信息.description("知识追寻者第一次操作OpenAPI！！！！！")// 版本号.version("v1")// 联系人.contact(new Contact("知识追寻者", "https://blog.csdn.net/youku1327", "lsc50534314@gmail.com"))// 声明许可.license("知识追寻者许可")// 许可路径，这边是我的github.licenseUrl("https://github.com/zszxz").build();return apiInfo;}
}

4.4 实体

/*** @Author lsc* <p> </p>*/
@Data
@ApiModel(description = "用户知识追寻者实体")
public class ZSZXZ {@ApiModelProperty(value = "姓名",dataType = "String")private String name;@ApiModelProperty(value = "邮件",dataType = "String")private String email;@ApiModelProperty(value = "爱好",dataType = "String")private String hobby;
}

4.5 controller

/*** @Author lsc* <p> </p>*/
@RestController
// 资源信息
@Api(value = "知识追寻者文档API")
public class SwaggerController {// 方法注释@ApiOperation(value = "获取用户")// 响应信息@ApiResponse(code = 200,message = "获取用户列表成功")@GetMapping("zszxz")public ResponseEntity getUser(){ZSZXZ zszxz = new ZSZXZ();zszxz.setName("知识追寻者");zszxz.setHobby("爱睡觉");zszxz.setEmail("不告诉你");return ResponseEntity.ok(zszxz);}// 方法注释@ApiOperation(value = "跟据用户编号获取用户")// 响应信息@ApiResponses({@ApiResponse(code = 200,message = "获取用户列表成功"),@ApiResponse(code = 204,message = "没有内容")})// 参数信息@ApiImplicitParam(name = "id", value = "用户编号", dataType = "ZSZXZ",required = true, paramType = "path")@GetMapping("zszxz/{id}")public ResponseEntity getUserById(@PathVariable Long id){ZSZXZ zszxz = new ZSZXZ();zszxz.setName("知识追寻者");zszxz.setHobby("爱睡觉");zszxz.setEmail("不告诉你");return ResponseEntity.ok(zszxz);}@PostMapping("zszxz")// 响应信息@ApiResponse(code = 201,message = "添加用户列表成功")// 方法信息@ApiOperation(value = "添加用户")public ResponseEntity addUser(@RequestBody ZSZXZ zszxz){System.out.println("save the user:"+zszxz);return ResponseEntity.ok("success save the user");}// 响应信息@ApiResponse(code = 200,message = "修改用户成功")@ApiOperation(value = "修改用户",notes = "修改用户")@PutMapping("zszxz/{id}")// 参数信息 多个参数使用注释中得内容, @RequestBody 修斯参数没必要写/*@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long",required = true,paramType = "path"),@ApiImplicitParam(name = "user", value = "用户", dataType = "ZSZXZ",required = true, paramType = "json")})*/@ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long",required = true,paramType = "path")public ResponseEntity updateUser(@PathVariable Long id ,@RequestBody ZSZXZ zszxz){System.out.println("update the user:"+zszxz);return ResponseEntity.ok("success update the user,the number is :"+id);}// 响应信息@ApiResponses({@ApiResponse(code = 200,message = "删除用户成功"),@ApiResponse(code = 401,message = "没有权限")})@ApiOperation(value = "删除用户")@DeleteMapping("zszxz/{id}")@ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long",required = true,paramType = "path")public ResponseEntity updateUser(@PathVariable Long id ){System.out.println("delete the user :"+id);return ResponseEntity.ok("delete the user :"+id);}}

4.6 生成结果

默认路径：localhost:8080/swagger-ui.html#/

4.7 查看实体

4.8 查询接口测试

打开测试查询接口：

测试结果：

4.9 添加用户测试

由于注解时偷懒没加example，所以这边测试要自己动手写测试数据；

测试结果如下

五结语

修改和删除就不测试了，很简单，读者自行测试；基本常用得注解使用都过了，其余得读者自行研究，总体来说使用还是很愉快，默认文档路径是可以修改得，读者自行搜索；源码请看作者博客专栏说明；