Swagger2
背景介绍
在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。这种做法存在以下几个问题：
1）API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；
2）难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况；
Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：
- 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本；
- 支持在线接口测试，不依赖第三方工具；
什么是Swagger2
Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：
- 接口的文档在线自动生成；
- 功能测试；
常用注解
| 注解 | 描述 |
|---|---|
| @Api | 将类标记为 Swagger 资源。 |
| @ApiImplicitParam | 表示 API 操作中的单个参数。 |
| @ApiImplicitParams | 允许多个 ApiImplicitParam 对象列表的包装器。 |
| @ApiModel | 提供有关 Swagger 模型的其他信息。 |
| @ApiModelProperty | 添加和操作模型属性的数据。 |
| @ApiOperation | 描述针对特定路径的操作或通常是 HTTP 方法。 |
| @ApiParam | 为操作参数添加额外的元数据。 |
| @ApiResponse | 描述操作的可能响应。 |
| @ApiResponses | 允许多个 ApiResponse 对象列表的包装器。 |
| @Authorization | 声明要在资源或操作上使用的授权方案。 |
| @AuthorizationScope | 描述 OAuth2 授权范围。 |
SpringBoot整合Swagger2
导入依赖
io.springfox
springfox-swagger2
2.9.2
swagger-models
io.swagger
com.github.xiaoymin
swagger-bootstrap-ui
1.8.5
io.swagger
swagger-models
1.5.22
创建Swagger配置类
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用 dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
//api接口包扫描路径
public static final String
SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
//指定当前Swagger API文档版本
public static final String VERSION = "1.0.0";
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
// 接口文档的基本信息
.apiInfo(apiInfo())
.select()
// 方法需要有ApiOperation注解才能生存接口文档
//.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 路径使用any风格
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
* 访问地址：http://项目实际地址/doc.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot中使用Swagger2构建RestFul APIs")
.description("测试系统")
//.termsOfServiceUrl("http://www.**.com")
.version(VERSION)
.build();
}
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
- 完成以上配置之后，通过mybatis-generator生成model和mapper；
- 创建IBookService及BookServiceImpl实现类；
- 创建BookController
综合案例
localhost：8080/doc.html
@Api
@Api注解用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。
| 属性 | 说明 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| produces | 返回的格式类型例如：“application/json, application/xml” |
| consumes | 接收请求参数的类型例如：“application/json, application/xml” |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
案例演示
@RestController
@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
@RequestMapping("/book")
public class BookController {
...
}
@ApiOperation
@ApiOperation注解用在方法上，说明方法的作用，每一个url资源的定义。
| 属性 | 说明 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| produces | 返回的格式类型例如：“application/json, application/xml” |
| consumes | 接收请求参数的类型例如：“application/json, application/xml” |
| hidden | 是否在文档中显示 |
| notes | 注释说明 |
| response | 返回的对象 |
| responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.，其他无效 |
| responseReference | 指定对响应类型的引用。指定的引用可以是本地的，也可以是远程的*将按原样使用，并覆盖任何指定的response()类 |
| responseHeaders | 响应旁边提供的可能标题列表 |
| httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
| code | http的状态码 默认 200 |
案例演示
@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",
produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody> queryAll(){
try {
return bookService.queryAll();
} catch (Exception e) {
e.printStackTrace();
return new JsonResponseBody<>(500,e.getMessage());
}
}
@ApiImplicitParam
@ApilmplicitParam 注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入；
| 属性 | 说明 |
|---|---|
| paramType | 参数放在哪个地方 |
| name | 参数名称 |
| value | 参数代表的含义 |
| dataType | 参数类型 |
| dataTypeClass | 参数类型 |
| required | 是否必要 |
| defaultValue | 参数的默认值 |
paramType
| 类型 | 作用 |
|---|---|
| path | 以地址的形式提交数据，用于restful接口。请求参数采用@PathVariable获取 |
| query | 直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取 |
| body | 以流的形式提交，仅支持POST。请求参数采用@RequestBody获取 |
| header | 参数在request headers里边提交。请求参数采用@RequestHeader获取 |
| form | 以form表单的形式提交，仅支持POST。 |
案例演示
@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){
JsonResponseBody json = bookService.selectByPrimaryKey(bookid);
return json.getData();
}
@ApiImplicitParams
@ApilmplicitParams 如果有多个参数，则需要使用多个 @ApilmplicitParam 注解来描述， 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中；
案例演示
@ApiOperation(value = "新增书本信息", notes = "新增书本信息"
,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
@ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),
@ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),
@ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody addBook(@RequestParam String bookname,
@RequestParam Double price,
@RequestParam String booktype){
return bookService.insert(Book.builder()
.bookid(UUID.randomUUID().toString().replace("-",""))
.bookname(bookname)
.booktype(booktype)
.price(price)
.build());
}
@ApiModel和@ApiModelProperty
@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候；
@ApiModelProperty注解描述一个model的属性。
| 属性 | 说明 |
|---|---|
| value | 字段说明 |
| name | 参数名称 |
| dataType | 参数类型 |
| hidden | 在文档中隐藏 |
| required | 是否必要 |
| example | 举例说明 |
| notes | 注释说明 |
案例演示
Controller
@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody editBook(@RequestBody Book book){
return bookService.updateByPrimaryKey(book);
}
注意：在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息，因为在这里的输入参数是实体对象，而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。
Book实体类
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {
/**
* 书本编号
*/
@ApiModelProperty(value="书本编号")
private String bookid;
/**
* 书本名称
*/
@ApiModelProperty(value="书本名称")
private String bookname;
/**
* 书本价格
*/
@ApiModelProperty(value="书本价格")
private Double price;
/**
* 书本类型
*/
@ApiModelProperty(value="书本类型")
private String booktype;
private static final long serialVersionUID = 1L;
}
@ApiParam
作用在方法的参数上，用来描述接口的参数信息(一个参设置一个)
@ApiParam必须与@RequestParam、@PathVariable和@RequestHeader一起使用。
| 属性 | 说明 |
|---|---|
| name | 参数名称 |
| value | 参数简单描述 |
| defaultValue | 描述参数默认值 |
| required | 是否为必传参数, false:非必传; true:必传 |
| allowMultiple | 指定参数是否可以通过多次出现来接收多个值 |
| hidden | 隐藏参数列表中的参数 |
| example | 非请求体(body)类型的单个参数示例 |
| examples | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例，仅适用于请求体类型的请求 |
案例演示
@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody addBooks(
@ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
@ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
@ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
return new JsonResponseBody<>();
}
生产环境下屏蔽Swagger2
为了保证接口文档的安全，禁用了生产环境的加载，具体说明请看：
参考地址：https://www.jianshu.com/p/fa3230ffb27c
一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!
一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!
一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!!
修改Swagger2配置类
添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2。
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用 dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
...
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
修改application.yml
修改application.yml文件，配置项目系统的运行环境（dev/test/prod）
spring:
#配置swagger2生产和测试环境不可用
profiles:
active: prod
使用maven package打包测试
运行测试
打开CMD，跳转到target目录，输入命令：java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置：
开发环境：dev；
生产环境：prod；
测试环境：test；
