SpringBoot整合Swagger及Swagger注解属性介绍

1 环境

JDK1.8

Tomcat 8.0.39

Spring 4.3.9.RELEASE

已完成项目

 

2 Swagger2的maven依赖

 

在项目根pom.xml中引入jar及其版本号。

<!-- 构建Restful API -->
<dependency>
    <groupId>io.springfox</groupId> 
    <artifactId>springfox-swagger2</artifactId> 
    <version>2.4.0</version> 
</dependency> 
<dependency> 
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

在根pom.xml中，设置版本号。如图2-a

 

图2-a

在根pom.xml中，引入jar包及版本。如图2-b

 

图2-b

在项目的核心包中的pom.xml中引入jar。如图2-c

 

图2-c

3 Swagger配置类

在项目中创建 一个类名为RestApiConfig的Swagger配置文件 

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.ComponentScan;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;



import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableWebMvc

@EnableSwagger2

@Configuration

@ComponentScan(basePackages ="com.hw.one.core.controller")

public class RestApiConfig extends WebMvcConfigurationSupport {

 @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

              .apiInfo(apiInfo())   

              .host("localhost:8080/api")

              .protocols(Sets.newHashSet("https","http"))  

                //.pathMapping("/")

                .select()

                //只生成被Api这个注解注解过的类接口            //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

                //只生成被ApiOperation这个注解注解过的api接口

                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                //生成所有API接口             //.apis(RequestHandlerSelectors.basePackage("com.hw.one.core.controller"))

                .paths(PathSelectors.any())

                .build();

    }



 private ApiInfo apiInfo() {

 return new ApiInfoBuilder()

 .title("ONE基础平台API")

 .description("ONE基础平台在线API文档，主要提供基础平台的所有功能实现接口。")

// .license("稳定版")

//             .termsOfServiceUrl("http://localhost:8080/dist/index.html")

// .contact(new Contact("ONE基础平台","http://192.168.15.246:8025/#/login","scsoft@163.com"))

 .version("2.0.0")

 .build();

    }

}

4 Swagger-UI配置

Swagger扫描解析得到的是一个json文档，对于用户不太友好。下面介绍swagger-ui，它能够友好的展示解析得到的接口说明内容。

  从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里，本文放入one-web/one-swagger 目录下。如图4-1-a

图4-1-a

修改dist/index.html文件，默认是从连接

http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写。

比如我的url值:http://localhost:8080/s/v2/api-docs  如图4-1-b

图4-1-b

 

Web.xml中过滤器的配置.如图4-1-c

图4-1-c

 

 

如果有认证，则不认证url前缀为v2/api-docs 。如图4-1-d

图4-1-d

 

 

页面访问地址：localhost:8080/dist/index.html . 如图4-1-e

图4-1-e

 

5 Controller类配置

5.1 类的注解配置

通过对类的注解，来规定类的特征。如图：5-1

图5-1

5.2 类注解属性说明

1. @Api：修饰整个类，描述Controller的作用，其各属性作用：

 

属性名称	属性特性描述
value	类概要描述
tags	用于资源或任何其他限定符的逻辑分组。如果设置这个值、value的值会被覆盖
description	对类的详细描述。
basePath	基本路径可以不配置。
position	如果配置多个Api 想改变显示的顺序位置。（已过时）
produces	响应类型定义属性："application/json, application/xml"。
consumes	请求类型定义属性"application/json, application/xml"。
protocols	定义类所使用的协议: http, https, ws, wss。
authorizations	高级特性认证时配置。
hidden	配置为true 将在文档中隐藏该方法。
response	操作相应类型。
responseContainer	声明一个响应容器，可以是 "List", "Set" or "Map"，其他无效。
httpMethod	请求类型："GET", "HEAD", "POST", "PUT", "DELETE",  "OPTIONS" ， "PATCH"。
code	http的状态码 默认 200。
extensions	扩展属性。

 

类注解在本项目中主要使用如下：

@Api() -用于类，表示标识这个类是swagger的资源 。
tags–表示说明 ，可以标识为类名。
value–也是说明，可以使用tags替代 tags。

description-对类的描述。（已过时）

如图5-2-a所示

图5-2-a

通过类的注解，swagger ui显示的效果图。如图5-2-b;

图5-2-b

5.3 方法注解的配置

通过对方法的注解，来规定方法的特征。如图5-3

图5-3

上述代码是Controller中的一个方法，@ApiOperation注解对这个方法进行了说明，@ApiOperation:注解方法，value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false。

@ApiParam注解对方法参数进行了说明。

 

注：忽略某个接口类，需要注解@ApiIgnore

@ApiIgnore:注解类、参数、方法，注解后将不在Swagger UI中显示。如图5-3-a

图5-3-a

5.4 方法注解属性说明

1.@ApiOperation注解：用在方法上，说明方法的作用，其中各属性的含义：

 

属性名称	属性特性描述
value	方法概要描述
tags	用于资源或任何其他限定符的逻辑分组。使用时，覆盖value值。
description	对方法的详细描述。
basePath	基本路径可以不配置。
position	如果配置多个Api 想改变显示的顺序位置，（已过时）。
produces	响应类型定义属性："application/json, application/xml"。
consumes	请求类型定义属性"application/json, application/xml"。
protocols	定义方法所使用的协议: http, https, ws, wss。
authorizations	高级特性认证时配置。
hidden	配置为true 将在文档中隐藏该方法。
response	操作相应类型。
responseContainer	声明一个响应容器，可以是 "List", "Set" or "Map"，其他无效。
httpMethod	请求类型："GET", "HEAD", "POST", "PUT", "DELETE",  "OPTIONS" ， "PATCH"。
code	http的状态码 默认 200。
extensions	扩展属性。

方法注解在本项目中主要使用如下：

@ApiOperation -用于方法说明，表示标识这个方法是swagger的资源 。
value用于方法描述 
notes用于方法的详细描述

如图5-4-a所示

图5-4-a

通过类的注解，swagger ui显示的效果图。如图5-4-b;

图5-4-b

 

2. @ApiImplicitParam的参数说明：

属性	取值	属性特性描述
paramType		查询参数类型
	path	以地址的形式提交数据，（用于restful接口）-->请求参数的获取：@PathVariable。
	query	请求参数放置于请求地址。（可以直接使用@RequestParam获取。）
	body	以流的形式提交 仅支持POST。
	header	请求参数放置于Request Header。（可以直接使用@RequestHeader获取。）
	form	以form表单的形式提交 仅支持POST。
dataType		参数的数据类型 只作为标志说明，并没有实际验证。
	Long
	String
name		接收参数名
value		接收参数的意义描述
required		参数是否必填
	true	必填
	false	非必填
defaultValue		默认值

 

方法参数注解在本项目中主要使用如下：

@ApiImplicitParam() 用于方法 ，表示单独的请求参数 
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
name–参数名
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

如图5-4-c

图5-4-c

通过类的注解，swagger ui显示的效果图。如图5-4-c;

图5-4-c

 

3. @ApiParam注解 (本项目暂时未用)

@ApiParam请求属性,使用方式：

 

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

属性名称	属性特性描述
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

 

4. @ApiResponse注解(本项目暂时未用)

@ApiResponse：响应配置，使用方式：

@RequestMapping(value = "/order", method = POST)

@ApiOperation(value = "Place an order for a pet", response = Order.class)

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

属性配置：

属性名称	属性特性描述
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	参考ApiOperation中配置

5. @ApiResponses注解 (本项目暂时未用)

@ApiResponses：响应集配置，使用方式：

@RequestMapping(value = "/order", method = POST)

@ApiOperation(value = "Place an order for a pet", response = Order.class)

@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

6. @ResponseHeader注解 (本项目暂时未用)

@ResponseHeader响应头设置，使用方法

@ResponseHeader(name="head1",description="response head conf")

属性名称	描述
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	参考ApiOperation中配置

 

7.其他 (本项目暂时未用)

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@ApiModelProperty：描述一个model的属性。