Springboot 项目集成 swagger

springfox 3.0 文档

简介

springfox 是spring 在swagger上进行二次开发的api doc框架。swagger是一套根据api自动生成api文档的规范，springfox在swagger基础上使用了注解代替之前的手动修改文件。如果不需要另外的限制和说明的话，只需要依赖springfox-boot-starter 包，即可完成自动化文档的集成。

优点

1. 自动生成api文档可以增加开发效率。
2. 使用简单，上手快，提供了可视化页面。
3. 可以对接口做一个分组。
4. 可以通过做一些配置来决定要不要暴露api文档。
5. 可以做一些简单的接口调用。

缺点

1. 如果需要增加注释，则需要使用大量的注解，文档要求越具体，需要用到的注解越多。
2. 请求方式需要指定哪一种，否则每一种都会生成一条。

使用场景

1. 前后端分离的开发的模式。多人配合开发的模式。

依赖

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

3.0开始，只需要依赖springfox-boot-starter就可以了，具体的依赖可以看这个jar的pom文件。核心依赖应该是springfox-swagger2和springfox-swagger-ui。

使用

1. 需要在SpringBootApplication增加@EnableOpenApi注解。

2. 增加配置类

   创建Docket的实例。一个实例表示一个分组，在springfox自带的ui里会展示地更清晰，且可以重新配置一些说明。

   demo

    /**
      * 文档基础信息。名字、描述、网站等
      * @return
      */
     private ApiInfo apiInfo() {
       // 联系方式
       Contact contact = new Contact(contactName, contactUrl, contactUrl);
       return new ApiInfo("接口文档", // 文档名称
               "接口文档。", // 文档描述
               "1.0",
               "",
               contact,
               "",
               "",
               new ArrayList<>());
     }
   
     @Bean
     public Docket docket() {
       return new Docket(DocumentationType.OAS_30) // 文档规范
               .enable(true) // 是否暴露文档
               .groupName("默认分组") // 分组名称
               .apiInfo(apiInfo()) // 文档基础信息
               .pathMapping("testserv") // 全局地址
               .host("127.0.0.1") // 域名。一般不需要填
               .select() // 配置访问的包和展示的接口
               .apis(RequestHandlerSelectors.basePackage(TestController.class.getPackage().getName()))
               .paths(PathSelectors.ant("/testserv/**"))
               .build()
               ;
     }
   

常用的注解说明

参数中的tags 如果不为空的话，会被分在单独一类

@ApiOperation

作用在方法和类上，可以对作用的方法或类加简介、注意点、标签、返回值类型等。

属性名	描述	默认值
value	简介	“”
notes	详细介绍	“”
tags	标签	“”
response	响应类型	Void.class
httpMethod	请求方式	“” 不填时为方法指定请求方式

@ApiIgnore springfox

作用在类、方法、参数上，标注这个类、方法、参数不会展示在界面上。

属性名	描述	默认值
value	不展示的原因	“”

@ApiParam

作用在被@RequestParam 标注的请求参数上，对参数加简介。

属性名	描述	默认值
name	参数名称	参数的名称
value	参数描述	“”
defaultValue	默认值	“”
allowableValues	可填的值	“”
required	是否必填	false
allowEmptyValue	允许为空	false

@ApiModel

作用在类上，给类增加一些描述

属性名	描述	默认值
value	类名	真实的类名
description	类的简介	“”
parent	父类	Void.class

@ApiModelProperty

作用在属性上，给属性增加一些描述

属性名	描述	默认值
value	属性的简介	“”
name	属性名	真实的属性名
allowableValues	可填的值	“”
dataType	属性类型	“”
required	是否必填	false
example	示例	“”