前后端分离之后，需要专门定义接口的规范。(OpenAPI规范)

Swagger是全球最大的基于OpenAPI规范开发工具。
Api管理，方便api测试，可以通过Swagger生成接口文档。
Swagger 有几个主要的产品。

Swagger Editor – 一个基于浏览器的 Open API 规范编辑器。

Swagger UI – 一个将 OpenAPI 规范呈现为可交互在线文档的工具。

Swagger Codegen – 一个根据 OpenAPI 生成调用代码的工具。

好处

可以生成文档形式的api并提供给不同的团队；
便于自测，便于领导查阅；
无响应过多冗余的word文档，可以保证是最新的。

注解 示例 描述
@ApiModel @ApiModel(value = “用户对象”) 描述一个实体对象
@ApiModelProperty @ApiModelProperty(value = “用户ID”, required = true, example = “1000”) 描述属性信息，执行描述，是否必须，给出示例
@Api @Api(value = “用户操作 API(v1)”, tags = “用户操作接口”) 用在接口类上，为接口类添加描述
@ApiOperation @ApiOperation(value = “新增用户”) 描述类的一个方法或者说一个接口
@ApiParam @ApiParam(value = “用户名”, required = true) 描述单个参数

UI显示

默认是通过http://${host}:${port}/swagger-ui.html访问的
如果使用了swagger-bootstrap-ui，样式会不一样，访问地址会变为http://${host}:${port}/doc.html

Api基本信息描述

即对应的ApiInfo的内容
image.png

API分组

对应的是groupName
image.png

请求列表

image.png

配置

配置类

注解

类上需要需要有两个注解：@Configuration和@EnableSwagger2

Docket类型函数

Docket类的函数上需要配置一个@Bean，为了Swagger2可以扫描到Controller
Docket最后需要build()一下

DocumentationType.SWAGGER_2

指定api的类型，一般是SWAGGER_2

apiInfo

定义api汇总信息。
需要传入一个ApiInfo类型的对象，可以在下面指定一个ApiInfo类型的函数
默认值为ApiInfo.DEFAULT

groupName

指定组名称
默认值为default

enabled

配置是否启用Swagger，默认值是true

this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
this.applyDefaultResponseMessages = true;
this.host = “”;
this.pathMapping = Optional.absent();
this.apiSelector = ApiSelector.DEFAULT;
this.enableUrlTemplating = false;
this.vendorExtensions = Lists.newArrayList();
this.documentationType = documentationType;

select&apis

指定controller的包
select().apis(RequestHandlerSelector.basePackage(“com.leanr.mycontroller”)

paths

paths(PathSelectors.any()) //这里是指定所有的Controller？

build

上面拼接完之后，需要执行一下这个函数，即return new Docket(DocumentationType.SWAGGER_2).apiInfo(xx).xxxx.build();

ApiInfo 类型函数

用于指定Api基本信息的地方

返回值可以是AipInfo的实例化对象，也可以使用ApiInfoBuilder()进行拼接，

image.png

  1. private ApiInfo apiInfo(){
  2.     return new ApiInfoBuilder().title("My_title").contact(new Contact("myname","http://my_website","mymail@test.com").description("这是一个api文档").version("版本号为v1.1").termOfServiceUrl("遵循的协议地址")
  3. }

image.png

title

设置页面标题

description

设置描述

version

设置版本

termsOfServiceUrl

组织链接

concat

设置联系人

license

许可信息

licenseUrl

许可链接

vendorExtensions

扩展信息

image.png

配置Controller

image.png

在Controller类上使用@ApiIgnore的话，这个Controller将不会出现在Swagger页面中

@ApiOperation，在controller中的方法上使用
其中httpMethod可以指定方法，例如”GET”

配置实体类

一般是配置BO实体类，在实体类上添加@ApiModel
@ApiProperty()，在具体字段上添加
value 字段说明
name 字段名
example 样例数据
required 是否必填
image.png
image.png

配置其他类返回对象

对于返回的结果，不一定都是数据库的信息，还有可能是某些工具类的返回值。
例如http工具类有返回json值，对应的值上的注解信息，也可以使用

常用注解

@Api

修饰整个类，描述Controller的作用

@ApiOperation

描述一个类的一个方法，或者说一个接口

@ApiParam

单个参数描述

@ApiModel

用对象来接收参数

@ApiModelProperty

用对象接收参数时，描述对象的一个字段

@ApiResponse

HTTP相应其中一个描述

@ApiResponses

HTTP响应整体描述

@ApiIgnore

使用该注解忽略这个API

@ApiError

发生错误返回的信息

@ApiImplicitParam

一个请求参数
@ApiImplicitParam中name和value的参数，required是是否必填，需要和QuerResponseResult类型的方法中的前两个入参保持一致，

@ApiImplicitParams

多个请求参数