1、背景
相信无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。
2、Swagger是什么?它能干什么?
发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
3、SpringBoot整合Swagger
1、Maven依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2、SwaggerConfig配置类
package com.lcy.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
@Configuration
//开启swagger2
@EnableSwagger2
public class SwaggerConfig {
// .groupName() 多人协作开发时需要配置多个分组
@Bean
public Docket docketZS() {
return new Docket(DocumentationType.SWAGGER_2).groupName("zhangsan");
}
@Bean
public Docket docketLS() {
return new Docket(DocumentationType.SWAGGER_2).groupName("lisi");
}
@Bean
public Docket docketWW() {
return new Docket(DocumentationType.SWAGGER_2).groupName("wangwu");
}
//配置了Swagger的Docket的bean实例
// enable(true) 是否开启swagger 默认为true
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("lichenyang")
.apiInfo(apiINfo())
.enable(true)
.select()
//配置要扫描接口的方式
/**
* RequestHandlerSelectors 配置要扫描接口的方式
* .basePackage() :指定要扫描的包
* .any():扫描全部
* .none():不扫描
* .withClassAnnotation():扫描类上的注解
* .withMethodAnnotation();扫描方法上的注解
*/
.apis(RequestHandlerSelectors.basePackage("com.lcy.controller"))
// .paths() 过滤什么路径
// .paths(PathSelectors.ant("/com/**"))
.build();
}
// 配置Swagger信息=apiInfo
private ApiInfo apiINfo() {
// 作者信息
Contact contact = new Contact("lcy", "https://lichenyang.blog.csdn.net/", "1105636101@qq.com");
return new ApiInfo(
"lcy的Swagger文档",
"生活不止眼前的苟且",
"version_1.0",
"https://lichenyang.blog.csdn.net/",
contact,
"Apacher 2.0",
"https://lichenyang.blog.csdn.net/",
new ArrayList<>()
);
}
}
3、controller类示例
package com.lcy.controller;
import com.lcy.pojo.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping(value = "Hello", method = RequestMethod.POST)
@ApiOperation("Hello 接口文档")
public String helloname(@ApiParam(value = "用户名") @RequestParam String name) {
return "Hello World!!!" + name;
}
}
4、swagger页面
4、Swagger常用注解
@Api 注解可以用来标记 Controller 的功能
@ApiOperation 注解用来标记一个方法的作用
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中
@ApiModel 如果参数是一个对象,则需要在对象所在的类上加上此注解
@ApiModelProperty 如果参数是一个对象,则需要在对应的属性上加上此注解,还需要在对象所在的类上加上 @ApiModel
@ApiIgnore 注解标识此参数可以忽略