前言
本文主要介绍了java框架相关的swagger2
1. swagger介绍
开源工具， 简化API 开发，帮助团队高效地大规模设计和记录 API。
2. springboot2.x整合swagger2.x
2.1 pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.2 编写配置类Swagger2Config
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build().apiInfo(new ApiInfoBuilder()
.title("API文档")
.description("API文档")
.version("1.0")
.contact(new Contact("公司","xxxx.com","email"))
.license("The License")
.licenseUrl("http://xxxx.com")
.termsOfServiceUrl("http://127.0.0.1/")
.build());
}
}
2.3 在需要api的类上面添加注解
@RestController
@Api(tags = "UserinfoCtrl", description = "用户信息相关")
public class TestSwaggerController {
@RequestMapping("/testswagger")
@ApiOperation(value = "获取用户信息", httpMethod = "GET", notes = "显示用户信息")
public Map<String, Object> fun() {
Map<String , Object> result=new HashMap<String,Object>();
result.put("test", "test");
System.out.println("ok");
return result;
}
}
2.4 浏览器访问：http://localhost:8080/swagger-ui.html#
测试是否生成了api：
3. swagger2主要注解的说明
3.1 @Api
用在类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源
@Api(value = "/user", description = "Operations about user")
其他属性值如下
value:url的路径值
tags:如果设置这个值、value的值会被覆盖
description:对api资源的描述
basePath:基本路径可以不配置
position:如果配置多个Api 想改变显示的顺序位置
produces:For example, “application/json, application/xml”
consumes:For example, “application/json, application/xml”
authorizations:高级特性认证时配置
hidden:配置为true 将在文档中隐藏
3.2 ApiOperation：
用在方法上，说明方法的作用，每一个url资源的定义,与Controller中的方法并列使用。
@ApiOperation(
value = "Find purchase order by ID",
notes = "",
response = Order,
tags = {"Pet Store"})
其他属性值如下
value:url的路径值
tags:如果设置这个值、value的值会被覆盖
description:对api资源的描述
position:如果配置多个Api 想改变显示的顺序位置
produces:For example, “application/json, application/xml”
consumes:For example, “application/json, application/xml”
protocols:Possible values: http, https, ws, wss.
authorizations:高级特性认证时配置
hidden:配置为true 将在文档中隐藏
response:返回的对象
responseContainer:这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code:http的状态码 默认 200
extensions:扩展属性
3.3 ApiParam
请求属性,与Controller中的方法并列使用。
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object")
其他属性值如下
name:属性名称
value:属性值
defaultValue:默认属性值
allowableValues:可以不配置
required:是否属性必填
access :不过多描述
allowMultiple: 默认为false
hidden:隐藏该属性
example:举例子
3.4 ApiResponse
响应配置，与Controller中的方法并列使用
@ApiResponse(code = 400, message = "Invalid user supplied")
其他属性值如下
code:http的状态码
message:描述
response:默认响应类 Void
reference:参考ApiOperation中配置
responseHeaders:参考 ResponseHeader 属性配置说明
responseContainer:参考ApiOperation中配置
3.5 ApiResponses
与Controller中的方法并列使用ApiResponses：响应集配置，使用方式：只有value属性
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
3.6 ResponseHeader
与Controller中的方法并列使用响应头设置
@ResponseHeader(name="head1",description="response head conf")
name:响应头名称
description:头描述
response:默认响应类 Void
responseContainer:参考ApiOperation中配置
3.7 其他
@ApiImplicitParams：用在方法上包含一组参数说明；
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪个地方
name：参数代表的含义
value：参数名称
dataType： 参数类型，有String/int，无用
required ： 是否必要
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应；
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息；
code： 响应码(int型)，可自定义
message：状态码对应的响应信息
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；
@ApiModelProperty：描述一个model的属性。
总结
本文主要介绍了java框架相关的swagger2，如果有任何疑问欢迎私信或者评论
原文链接：https://blog.csdn.net/qq_24018193/article/details/140033645