java框架-Spring Boot2.x整合Swagger2

系列文章目录

前言

本文主要介绍了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，如果有任何疑问欢迎私信或者评论