背景Open

???swagger2的作用swagger2常用工具组件二、Springfox三、springBoot使用swagger2简单示例四、Swagger-UI使用五、配置文件1、配置类给docket上下文配置api描述信息2、配置类扫描包3、自定义注解设置不需要生成接口文档的方法▶Target-描述当前的注解可以定义在什么资源上▶Retention-当前注解在什么时候有效▶示例4、配置路径范围配置paths()六、Swagger2常用注解常用注解ApiApiOperationApiParamApiImplicitParam-sApiModel、ApiModelProperty一、swagger2

我们后端在编写项目的时候往往都会在代码上加上注释方便自己以后的修改和维护和方便别人的理解。

但是对对前后端分离的项目前端人员写前端代码后端人员编写后端的代码。

这样的话当前端需要调用我们后端的接口的时候就会来找我们询问参数以及请求的接口路径。

如果每次都来问的话就会很繁琐。

所以我们要讲我们自己编写的代码生成一个api文档里面描述了我们各种接口调用规则我们只需要将这个api文档交给前端人员即可。

前端人员就可以根据我们提供的文档获取到他们需要调用的接口路径以及参数信息。

Open

Specification)以前叫做Swagger规范是RESTAPI的API描述格式。

Open

或GET。

I每个操作的参数。

包括输入输出参数。

·认证方法。

连接信息声明使用团队和其他信息。

Open

API规范可以使用YAML或JSON格式进行编写。

这样更利于我们和机器进行阅读。

swagger2

是一个规范和完整的框架用于生成、描述、调用和可视化Restful风格的web服务

用白话说就是后端人员写完代码后不想写开发文档就嵌用api注解代码启动访问固定的路径

swagger2常用工具组件

Markdown具有实时预览描述文件的功能。

还要自己写需要会json或者yaml

2、Swagger

API规范呈现为交互式API文档。

用可视化U展示描述文件。

注解

3、Swagger

Codegen将OpenAPI规范生成为服务器存根和客户端库。

通过Swagger

4、Swagger

Hub集成了上面所有项月的各个功能你可以以项目和版本为单位将你

二、Springfox

使用Swagger时如果碰见版本更新或迭代时只需要更改Swagger的描述文件即可。

yml或json

Spring-fox是根据代码生成接口文档所以正常的进行更新项目版本修改代码即可

Spring-fox利用自身AOP

官网http://springfox.github.io/springfox/

源码https://github.com/springfox/springfox

!--swagger2的依赖--dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependency!--视图逻辑swagger-ui--dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/versionscopecompile/scope/dependency▶先写一个controller里面有三种请求方法自定义、get、post

RestController//方法中所有的返回值都相当于加了一个ResponseBody

public

{PostMapping(/getUserById)//post请求public

String

post:根据id获取User;}GetMapping(/getUsers)//get请求public

String

get:获取所有的User;}RequestMapping(/req)//这种请求方式是不限制请求方式的任意请求方式都可以访问public

String

springfox提供的注解代表swagger2相关技术开启会扫描当前类所在包及子包中所有的类型中的注解,

▶运行启动类访问路径http://localhost:8080/swagger-ui.html

访问swagger-ui.html后可以在页面中着到所有需要生成接口文档的控制器名称

basic-error-controller中是springBoot内部的关于错误提示的controller。

MyController自己写的。

其中有get和post的请求还有一个没有限制请求方式的方法。

……

四、Swagger-UI使用

显示控制器显示控制器中的请求方法路径地址的处理、参数、名字等简单测试请求以及返回的响应结果描述

五、配置文件

上面提到过在视图中有些东西可以修改与本项目的内容无关就需要通过配置类来实现修改

Configuration

Docket(DocumentationType.SWAGGER_2);//API帮助文档的描述信息ApiInfo

apiInfo

//是文档发布者的网站地址。

企业网站adminbjsxt.com)

//文档发布者的电子邮箱).title(swagger文档标题).description(swagger2

是一个规范和完整的框架用于生成、描述、调用和可视化Restful风格的web服务,开发帮助文档).version(1.1).build();docket.apiInfo(apiInfo);return

docket;}

}文档运行路径http://localhost:8080/swagger-ui.html对比上张图观察上下文配置api描述信息都是修改的文档的哪个地方。

2、配置类扫描包

//获取Docket中的选择器。

返回ApiSelectorBuilder。

构建选择器的。

如:扫描什么包的注解.apis(RequestHandlerSelectors.basePackage(com.wxy.springboot_swagger.controller));

//规则,设定扫描哪个包包含子包3、自定义注解设置不需要生成接口文档的方法

ElementType.METHOD可以定义在方法上EIementType.TYPE可以定义在类型上ElementType.FIELD可以定义在属性上ElementType.PARAMETER可以定义在方法参数上……

RetentionPolicy.RUNTIME-运行时有效(常用)RetentionPolicy.SOURCE一源码中有效RetentionPolicy.CLASS-字节码有效

▶示例

{ElementType.METHOD,ElementType.TYPE})

Retention(RetentionPolicy.RUNTIME)

public

{//自定义注解中的属性。

相当于MyAnnotationSwagger(value)String

value()

}2.自定义注解的使用实现controller中“req()”方法不在文档视图中显示

要在controller中req()的方法上添加注解MyAnnotationSwagger

docket

//获取Docket中的选择器。

返回ApiSelectorBuilder。

构建选择器的。

如:扫描什么包的注解//.apis(RequestHandlerSelectors.basePackage(com.wxy.springboot_swagger2.controller))

//规则,设定扫描哪个包包含子包.apis(Predicates.not(

//取反false-true

true-falseRequestHandlerSelectors.withMethodAnnotation(

//withMethodAnnotation:当方法上有注解时返回trueMyAnnotationSwagger.class))

//重新构建Docket对象测试只有get和post两个方法了

Predicates.and()

.paths(PathSelectors.regex(/swagger/.*)

//使用正则表达式约束生成API文档的路径地址。

//控制器访问路径以swagger开头的。

RequestMapping(/swagger)

//多个规则符合任意一个即可通过。

PathSelectors.regex(pathRegex:/swagger/.*),PathSelectors.regex(pathRegex:/swagger2/.*),PathSelectors.regex(pathRegex:/.*))

)六、Swagger2常用注解

swagger通过注解表明该接口会生成文档包括接口名、请求方法、参数、返回信息的等等。

tags给当前类型定义别名可以有多个。

定义几个别名在ui视图中就显示几个控制器访问菜单。

description定义描述

ApiOperation描述一个类的一个方法或者说一个接口ApiParam单个参数描述ApiModel描述实体类型用对象来接收参数ApiModelProperty用对象接收参数时描述对象的一个字段ApiImplicitParam在方法上描述方法的一个请求参数ApiImplicitParams多个请求参数ApiIgnore忽略当前注解描述的方法或类型不生成api帮助文档

Api

{MyController,Swagger测试控制器},description

测试API类型描述信息)

PostMapping(/getUserById)//post请求ApiOperation(value

post方法执行新增操作,

明值对)})ApiModel、ApiModelProperty

/***

描述一个实体类型。

这个实体类型如果成为任何一个生成api帮助文档方法的*

ApiModel(value

myEntity.password);}Overridepublic

int

RequestMapping(/testEntity)public

MyEntity