swagger配置以及注解
依赖
<!-- /artifact//springfox-swagger2 -->
<dependency>
<groupId></groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- /artifact//springfox-swagger-ui -->
<dependency>
<groupId></groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
一、配置
常用配置参数表：
| 类型 | 名称 | 方法 | 作用 |
|---|---|---|---|
| ApiInfo | ApiInfo | apiInfo() | 配置api的基本信息 |
| String | groupName | groupName() | 配置组的名称 |
| boolean | enabled | enabled() | swagger的开关 |
| boolean | applyDefaultResponseMessages | applyDefaultResponseMessages() | 是否使用默认响应消息 |
| String | host | host() | 请求路径信息 |
配置
对apiInfo的配置需要借助于ApiInfoBuilder类来重构，也就是利用它的build()方法来实例化apiInfo
我们去看一下ApiInfoBuilder的源码，有那些可配置的参数：
private String title;
private String description;
private String termsOfServiceUrl;
private Contact contact;
private String license;
private String licenseUrl;
private String version;
然后去看下ApiInfo类的默认配置，基本上就知道了配置的位置在哪里了
public static final ApiInfo DEFAULT = new ApiInfo("Api Documentation",
"Api Documentation", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "/licenses/LICENSE-2.0", new ArrayList<VendorExtension>());
1.1 apiInfo参数表
| 类型 | apiInfo参数名 | 作用 | 默认值 |
|---|---|---|---|
| String | title | 标题 | Api Documentation |
| String | description | 描述 | Api Documentation |
| String | termsOfServiceUrl | 服务条款网址 | urn:tos |
| String | license | 许可 | Apache 2.0 |
| String | licenseUrl | 许可链接 | /licenses/LICENSE-2.0 |
| String | version | 版本 | 1.0 |
| Contact | Contact | 维护人信息 | null |
apiInfo配置中，有一个Contact的属性
1.2 contact参数表
| 类型 | 参数名 | 作用 | 默认值 |
|---|---|---|---|
| String | name | 维护人姓名 | “” |
| String | url | 维护人url地址 | “” |
| String | 维护人邮箱 | “” |
1.3 配置例子
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//标题
.title("sky的swagger案例Demo")
//描述
.description("用于讲解关于swagger的基本配置使用以及注解")
//许可
.license("sky 2021/06/13")
//许可链接
.licenseUrl("")
//服务条款网址
.termsOfServiceUrl("")
//版本
.version("1.0")
//维护人信息
.contact(new Contact("sky","","xxx@"))
.build();
}2. groupName配置
这个注解用于配置当前docket的名称，每一个docket都相当于一个组
比如说这个docket只控制登陆相关的controller，配置这个属性就可以找到相应的注解类
由于这个是String类型，所以我们直接进行使用就可以了
//docket1是显示auto的
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("二组").select()
.apis((""))
.paths(("/auto/**")).build();
}
//docket2是显示admin的
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("二组").select()
.apis((""))
.paths(("/admin/**")).build();
}
3. enabled配置
这个是Swagger开关，源码描述是默认为true，如果为false就不能能在浏览器中访问了
private boolean enabled = true;4. applyDefaultResponseMessages配置
这个是应用默认响应消息,默认值为true
如果为false的话就会启用ResponseMessages
然后通过调用globalResponseMessage()写入自己的响应消息
源码如下：
//默认为true
private boolean applyDefaultResponseMessages = true;
//当 applyDefaultResponseMessages = false 时,这个就会启用
private final Map<RequestMethod, List<ResponseMessage>> responseMessages = newHashMap();
//然后就要你自己配置调用globalResponseMessage()，他的写入源码
public Docket globalResponseMessage(RequestMethod requestMethod,
List<ResponseMessage> responseMessages) {
(requestMethod, responseMessages);
return this;
}
5. host
这个是文档的host信息，在swagger中测试的时候，访问的路径就是通过host属性来控制的
private String host = "";
//默认值为空，
//但是实际上显示的值为项目地址也就是：localhost:8080/
6.完整配置
@Configuration
@EnableSwagger2
@Profile({"test"})
public class SwaggerConfig {
@Value("${}")
private boolean enable;
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("二组").select()
.apis((""))
.build();
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("一组").select().build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//标题
.title("lzl的swagger案例Demo")
//描述
.description("用于讲解关于swagger的基本配置使用以及注解")
//许可
.license("lzl 2021/06/13")
//许可链接
.licenseUrl("/qq_26103133?spm=1001.2101.3001.5343")
//服务条款网址
.termsOfServiceUrl("")
//版本
.version("1.0")
//维护人信息
.contact(new Contact("lzl","","2243716932@"))
.build();
}
}二、注解
swagger常用注解表
| 名称 | 使用 | 描述 |
|---|---|---|
| @Api | controller类上 | 对请求类的说明 |
| @ApiIgnore | controller类上 | 隐藏类swagger不会显示 |
| @ApiModel | 实体类上 | 说明实体类的用途 |
| @ApiModelProperty | 实体类参数上 | 说明实体类属性的的含议 |
| @JsonIgnore | 实体类参数上 | 隐藏该实体类属性 |
| @ApiOperation | 方法上 | 方法的说明 |
| @ApiImplicitParams | 方法上组合使用 | 方法的参数的说明 |
| @ApiImplicitParam | 方法上 | 用于指定单个参数的说 |
| @ApiResponses | 方法上组合使用 | 方法返回值状态码的说明 |
| @ApiResponse | 方法上 | 指定单个返回值状态码的说明 |
| @ApiParam | 方法参数上 | 单个方法参数 |
1. @Api 说明controller类
@api的常用参数表
| 类型 | 名称 | 描述 |
|---|---|---|
| String[] | tags | 标题分组 |
| String | description | 描述 |
| String | produces | 输出 |
| String | consumes | 输入 |
| String | protocols | 请求规范 |
| Authorization[] | authorizations | 安全设置 |
| boolean | hidden | 是否启用 |
没写上的都停用了，没讲的必要
1.1 tags 标题
就是当前controller类的标题分组，是数组类型的可以写多个标题。例如：登陆模块、注册模块
1.2 description 描述
一般用于对标题的补充说明。例如：包含注册接口、登陆接口、权限控制接口等等
1.3 produces 输出规范
源码描述是这样子的：
/**
* Corresponds to the `produces` field of the operations under this resource.
* <p>
* Takes in comma-separated values of content types.
* For example, "application/json, application/xml" would suggest the operations
* generate JSON and XML output.
* <p>
* For JAX-RS resources, this would automatically take the value of the {@code @Produces}
* annotation if such exists. It can also be used to override the {@code @Produces} values
* for the Swagger documentation.
*
* @return the supported media types supported by the server, or an empty string if not set.
*/
String produces() default "";
大致意思就是说，你可以通过他控制输出的类型，"application/json, application/xml"是输出json和·xml类型
但是我没用过
1.4 consumes 输入规范
和produces 是一样的，只不过这个是输入的规范，还是没用过
1.5 authorizations 安全控制
这个我也没用过，因为我个人很少通过security去搞安全，一般都是直接@Profile，然后通过控制版本来实现的，这个比较简单方便，正式上线的时候通过shiro直接把链接封掉就好了
/**
* Corresponds to the `security` field of the Operation Object.
* <p>
* Takes in a list of the authorizations (security requirements) for the operations under this resource.
* This may be overridden by specific operations.
*
* @return an array of authorizations required by the server, or a single, empty authorization value if not set.
* @see Authorization
*/
Authorization[] authorizations() default @Authorization(value = "");
1.6 hidden
控制当前类是否在swagger中显示，还是没用过，而且我在写这个的时候实验了一下，好像没作用
/**
* Hides the operations under this resource.
*
* @return true if the api should be hidden from the swagger documentation
*/
boolean hidden() default false;
1.7 完整配置
综上所述我们api注解中常用的配置就是两个：tags，description，其他的基本上也都不怎么用
@Api(tags = {"登陆模块"},description = "相当牛逼的东西")2. @ApiIgnore 隐藏controller类
标注了该注解之后，扫描controller类就会忽略掉这个类，在swagger-ui里面就看不到了
这个注解只有一个参数，这个参数value()外面是看不到的，只能在代码里面看到，相当于注释
/**
* A brief description of why this parameter/operation is ignored
* @return the description of why it is ignored
*/
String value() default "";
使用这个注解时我们不需要填写参数
@ApiIgnore
//直接将注解放在类上就可以使用了3. @ApiModel 说明实体类
用于说明实体类的用途
这个注解的参数还是蛮多的，但是常用的就两个：value和description
value是显示在Models中，该实体类叫什么名字，description还是描述
@ApiModel(value = "admin-auto" ,description = "管理员表")
4. @ApiModelProperty 说明实体类属性
用与说明实体类的属性，这个注解的参数还是蛮多的，这些注解效果需要在swagger-ui的models里面查看
常用参数表：
| 类型 | 名称 | 描述 |
|---|---|---|
| String | value | 描述 |
| String | allowableValues | 许可值 |
| String | dataType | 数据类型 |
| boolean | required | 是否需要 |
| int | position | 排序 |
| boolean | hidden | 隐藏属性 |
| String | example | 示例值 |
| boolean | readOnly | 标记只读 |
| boolean | allowEmptyValue | 允许为空 |
4.1 value描述
一般写这个参数是干嘛的，
例如：
@ApiModelProperty(value = "用户账号")
private String username;
4.2 allowableValues 许可值
一般用于标注数值范围，这个只是提示，但是你不按提示的输入一样能输入的，只是给前段测试一个提示
例如：性别，后台是0代表女1代表男，你就可以写提示上去，限制0,1两个数
//标记输入值，在swagger页面显示上就会出现这个参考值为0和1
@ApiModelProperty(allowableValues="0,1" )
private int age;
//标记范围，1-99之间的数值
@ApiModelProperty(allowableValues="range(1,99)" )
private int age;
//标记范围1-无穷大
@ApiModelProperty(allowableValues="range(1,infinity)" )
private int age;
4.3 dataType 数据类型
用于覆盖默认的数据类型，没用过
源码这么写的：
/**
* The data type of the parameter.
* <p>
* This can be the class name or a primitive. The value will override the data type as read from the class
* property.
*/
String dataType() default "";
4.4 required 是否需要
告诉前端该参数为必填项
//为true后swagger-ui就会显示该参数为必填选项
@ApiModelProperty(required = true)
private int age;4.5 position 排序
对属性显示顺序进行排序
下面代码显示顺序就是
@ApiModelProperty(value = "登陆账号",position = 0)
private String username;
@ApiModelProperty(required = true,position = 2)
private String sex;
@ApiModelProperty(required = true,position = 1)
private int age;
4.6 hidden 是否隐藏
该值如果为true就隐藏该属性 和 @JsonIgnore类似
@ApiModelProperty(required = truehidden = true)
private int age;
4.7 example
赋予属性一个默认值，当然类型是String类型的，你可以理解为文本
@ApiModelProperty(example ="123")
private int age;
4.8 readOnly
标记只读，字面意思
@ApiModelProperty(readOnly=true)
private int age;
表现出来的效果就是这样子的，展现出来的默认值
post请求
{
"username": "string",
"sex": "string"
}
get请求
{
"age": 0,
"username": "string",
"sex": "string"
}当然你要是强行要写，他也是能写的，只是他不会给你自动展示那个字段，要你自己去手写
4.9 allowEmptyValue
标记该字段是否可以为空，同理也只是提示，你要是后台没写控制代码，一样能传空值
@ApiModelProperty(allowEmptyValue=true)
private int age;5. @ JsonIgnore 隐藏实体类属性
和 hidden=true 类似，用于隐藏该实体类字段，标注在实体类的参数上
@JsonIgnore
@ApiModelProperty(required = true,position = 2)
private String sex;6. @ApiOperation 方法的说明
@ApiOperation 常用参数表：
| 类型 | 名称 | 描述 |
|---|---|---|
| String | value | 对方法的简要说明 |
| String | notes | 对方法的详细说明 |
| String[] | tags | 分组标题 |
| String | responseContainer | 包装响应容器 |
| String | httpMethod | method字段值 |
| boolean | hidden | 是否隐藏 |
| int | code | code状态码 |
| String | produces | 输出格式 |
| String | consumes | 输入格式 |
6.1 value 简要说明
这个参数是对方法的简要说明，源码写的是：
Provides a brief description of this operation. Should be 120 characters or less
建议在120字以下，不过应该也没人拿简要说明写作文吧？
例如：登陆方法
6.2 notes 详细说明
这个参数是对简要说明的的补充说明，详细说明
例如：包含了微信登陆，QQ登陆，短信登陆，账号密码登陆的登陆方法，返回一个Admin实体类
@ApiOperation(value = "登陆方法",notes = "微信登陆，QQ登陆，短信登陆，账号密码登陆的登陆方法，返回一个Admin实体类")
6.3 tags 分组标题
每一个tags都是一个标题分组，你可以如果在加上了这个参数，参数值是没有的标题分组就会新建一个
已有的标题分组就会加入进去，例如：有两个controller类
//一个标题分组是ao模块
@RestController
@RequestMapping("ao")
@Api(tags = {"ao模块"},description = "非常牛逼的东西",basePath = "",hidden = true,produces = "application/xml")
public class AOController {
@Autowired
AutoService autoService;
@ApiOperation(value = "登陆方法",notes = "微信登陆，QQ登陆，短信登陆，账号密码登陆的登陆方法，返回一个Admin实体类",tags ="登陆模块" )
@RequestMapping(value = "/set",method = )
public AdminEntity set( String name){
AdminEntity adminEntity=();
return adminEntity;
}
}
----------------------------------------------------------------
//一个是登陆模块
@RestController
@RequestMapping("auto")
@Api(tags = {"登陆模块"},description = "相当牛逼的东西")
public class AutoController {
@RequestMapping(value = "/set",method = )
public AutoEntity setAll(@RequestBody AutoEntity autoEntity){
List<Integer> list = new ArrayList<>();
(123);
(0);
return autoEntity;
}
}那么他们呈现出来的结果就是，ao模块有一个方法/ao/set ，登陆模块有两个方法/ao/set方法以及/auto/set方法
6.4 responseContainer 包装响应容器
声明响应容器，没用过，给兄弟们看源码
//Declares a container wrapping the response.
//Valid values are "List", "Set" or "Map". Any other value will be ignored.
String responseContainer() default "";
6.5 httpMethod method字段值
这个参数如果你不写，他就会默认读取方法上的注解，就会出现一种情况，你直接使用@RequestMapping注解的
时候没有声明method类型，就会直接出来"GET", “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” ,“PATCH”
很多种类型的接口文档。而且即使是你声明了method类型，然后在用这个参数的话，参数会覆盖掉你声明的类型
例如：
@ApiOperation(value = "德莱文",responseContainer="Map",httpMethod="PUT")
@RequestMapping(value = "/set",method = )
public AutoEntity setAll(@RequestBody AutoEntity autoEntity){
List<Integer> list = new ArrayList<>();
(123);
(0);
return autoEntity;
}
呈现出来的结果为PUT类型
6.6 hidden 是否隐藏
该参数用于隐藏该controller类的该方法，标注之后就不在swagger-ui里面显示了
@ApiOperation(value = "德莱文",hidden = true)
@RequestMapping(value = "/set",method = )
public AutoEntity setAll(@RequestBody AutoEntity autoEntity){
List<Integer> list = new ArrayList<>();
(123);
(0);
return autoEntity;
}
这样做的效果就是，swagger-ui不会显示这个方法
6.7 code code状态码
这个不需要改，看看就行了,默认值为200
/**
The HTTP status code of the response.
The value should be one of the formal <a target="_blank" href="http:///Protocols/rfc2616/">HTTP Status Code Definitions</a>.
*/
int code() default 200;
6.8 produces 输出格式
标注输出格式，表示以什么类型输出，但是只是表示，提示前端而已，例如：
application/json, application/xml
6.9 consumes 输入格式
标注输入格式，与produces 一样
7. @ApiImplicitParam方法参数说明
@ApiImplicitParam常用参数表：
| 属性 | 名称 | 描述 |
|---|---|---|
| String | name | 名称 |
| String | value | 简要描述 |
| String | defaultValue | 描述默认值 |
| String | allowableValues | 许可值 |
| boolean | required | 是否需要 |
| boolean | allowMultiple | 是否为集合 |
| String | dataType | 参数数据类型 |
| Class<?> | dataTypeClass | 参数类 |
| String | paramType | 参数类型 |
| String | example | 非实体类例子 |
| Example | examples | 实体类例子 |
| boolean | allowEmptyValue | 允许为空 |
| boolean | readOnly | 只读 |
7.1 name 名称
这个属性就是名字，推荐是和形参写一样的，源码描述是这样的
/*
Name of the parameter.
For proper Swagger functionality, follow these rules when naming your parameters based on {@link #paramType()}:
If {@code paramType} is "path", the name should be the associated section in the path.
For all other cases, the name should be the parameter name as your application expects to accept.
*/
7.2 value 简要描述
字面意思
7.3 defaultValue 默认值
字面意思
7.4 allowableValues 许可值
这个和@ApiModelProperty 的allowableValues 属性是一样的，写法也是一样的
7.5 required 是否需要
默认为false，为true就提示为必填参数，当然只是提示
7.6 allowMultiple 是否为集合
在我的理解中是集合的意思，源码描述是这样的。是否允许参数出现多次接收多个值
默认为false，为true就是允许
pecifies whether the parameter can accept multiple values by having multiple occurrences.
7.7 dataType 参数数据类型
这个基本上是不写的，但是也有特殊情况，比如说我们这么写，传参的时候name，传过来就是int类型
你不写的话，就会默认读取你的参数类型，写了就会覆盖掉
@ApiOperation(value = "登陆方法",notes = "微信登陆，QQ登陆，短信登陆，账号密码登陆的登陆方法，返回一个Admin实体类",tags ="登陆模块" )
@ApiImplicitParam(name = "name",defaultValue = "wdnmd",dataType = "int")
@RequestMapping(value = "/set",method = )
public AdminEntity set( String name){
AdminEntity adminEntity=();
return adminEntity;
}
然后控制台就会报错，就会：
Illegal DefaultValue wdnmd for parameter type integer
7.8 dataTypeClass 参数实体类
这个和dataType 类似，只不过一个是基本数据类型一个是实体类
7.9 paramType 参数类型
指定参数请求类型，有效值是path，query， body， header，form，例如
@ApiImplicitParam(name = "name",defaultValue = "wdnmd",paramType="body")
@RequestMapping(value = "/set",method = )
public AdminEntity set( String name){
AdminEntity adminEntity=();
return adminEntity;
}
7.10 example 非实体类例子
这个是例子，也就是要postman时候的默认例子，前面的那个defaultValue 默认值是显示的默认值
这两个是不一样的，侧重点不一样，这个如果不写，那默认例子值就是defaultValue 的值
7.11 examples 实体类例子
实体类例子的时候，就用这个属性，不使用defaultValue 属性，
当然我也没用过，我一般都是@RequestBody，不会直接接收实体类类型
7.12 allowEmptyValue 允许为空
字面意思，是否允许空值
7.13 readOnly 只读
写入的时候，swagger-ui不会给你显示这个参数，当然你可以手动写上去
8.@ApiImplicitParams注解
这个注解是与@ApiImplicitParam注解结合使用的，无法单独使用
例如：
@ApiOperation(value = "登陆方法",notes = "微信登陆，QQ登陆，短信登陆，账号密码登陆的登陆方法，返回一个Admin实体类",tags ="登陆模块" )
@ApiImplicitParams({
@ApiImplicitParam(name = "name",defaultValue = "wdnmd",value="账号"),
@ApiImplicitParam(name = "pass",defaultValue = "123456",value="密码")
})
@RequestMapping(value = "/set",method = )
public Object set(@RequestParam("name") String name,@RequestParam("pass")String pass){
(name);
(pass);
return pass;
}9.@ApiResponse注解 返回值状态码
该注解用于描述状态码
主要参数就两个 ：code 状态码以及message 描述信息
例如：
@ApiResponse(code = 200,message = "成功无错")
10.@ApiResponses注解
这个与@ApiImplicitParams相似，需要和@ApiResponse结合使用
例如：
@ApiResponses({
@ApiResponse(code = 200,message = "成功无错"),
@ApiResponse(code = 404,message = "没找到"),
@ApiResponse(code = 405,message = "不知道什么错"),
})11.@ApiParam注解 单个参数说明
这个参数的属性与@ApiImplicitParam是类似的，只是写法上不同
@ApiImplicitParam是写在方法上，他是写在属性前，但是不太推荐这种写法
public Object set(@RequestParam("name")
@ApiParam(value = "username") String name,
@RequestParam("pass")String pass){
(name);
(pass);
return pass;
}