Swagger2

Swagger

1、Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

1.1 swagger基础依赖介绍

1.   

2.        io.springfox  

3.        springfox-swagger-ui  

4.        2.6.1  

5.          

6.              

7.                guava  

8.                com.google.guava  

9.              

10.          

11.      

12.      

13.        io.swagger  

14.        swagger-annotations  

15.        1.5.4  

16.      

17.   

18.      

19.        io.springfox  

20.        springfox-swagger2  

21.        2.6.1  

22.          

23.              

24.                swagger-annotations  

25.                io.swagger  

26.              

27.              

28.                guava  

29.                com.google.guava  

30.              

31.          

32.      



 

 io.springfox

 springfox-swagger-ui

 2.6.1

 

 

 guava

 com.google.guava

 

 

 

 

 io.swagger

 swagger-annotations

 1.5.4

 

 

 io.springfox

 springfox-swagger2

 2.6.1

 

 

 swagger-annotations

 io.swagger

 

 

 guava

 com.google.guava

 

 

 

 

springfox-swagger2是API获取的包，springfox-swagger-ui是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

1.2 swagger-maven-plugin依赖

1.   

2.             

3.           org.apache.maven.plugins  

4.           maven-javadoc-plugin  

5.             

6.               UTF-8  

7.               UTF-8  

8.               **false**  

9.             

10.             

11.             

12.               com.github.kongchen  

13.               swagger-maven-plugin 

14.                 3.1.4 

15.                 

16.                     

17.                         

18.                           **false**  

19.                             

20.                           

21.                                com.chinamobile.cmss.bdoc.controller

22.                             

23.                             

24.                                 http

25.                                                       localhost:9098  

26.                           /cmh/v1  

27.                             

28.                                 

29.                               v1  

30.                               bc-bdoc-cmh-plugin 底层服务开通插件 REST API  

31.                                 

32.                                     

33.                                 

34.                                 

35.                                   [email protected]  

36.                                   Jianya Liao  

37.                                 

38.                                 

39.                                   http://10.254.2.95/licenses/LICENSE-CMSS.txt  

40.                                   The CMSS Software License, Version 1.0  

41.                                 

42.                             

43.                             

44.                             

45.                             

46.                           ${basedir}/target/generated/swagger-ui  

47.                           bc-bdoc-cmh-plugin  

48.                         

49.                     

50.                 

51.                 

52.                     

53.                       compile  

54.                         

55.                           generate  

56.                         

57.                     

58.                 

59.             

其中： com.chinamobile.cmss.bdoc.controller 是配置web项目Controller中的api；

${basedir}/target/generated/swagger-ui 

2、Swagger注解

Swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等，https://github.com/kongchen/swagger-maven-plugin
|注解 |说明|
@Api 修饰整个类，描述Controller的作用；
@ApiOperation 描述一个类的一个方法，或者说一个接口；
@ApiParam 单个参数描述；
@ApiModel 用对象来接收参数
@ApiProperty 用对象接收参数时，描述对象的一个字段；
@ApiResponse HTTP响应其中1个描述；
@ApiResponses HTTP响应整体描述；
@ApiIgnore 使用该注解忽略这个API；
@ApiError 发生错误返回的信息；
@ApiParamImplicitL 一个请求参数；
@ApiParamsImplicit 多个请求参数；

2.1 @Api

（1）在类上添加注解@Api

image.png

（2）访问

image.png

2.2 @ApiOperation

（1）在rest ful接口方法上添加@ApiOperation

image.png

（2）访问

image.png

2.3 @ApiParam

（1）在参数前添加@ApiParam

image.png

（2）访问

image.png

3、创建Swagger启动类

1）在项目启动类“APP”同级包目录下建立一个Swagger启动类“Swagger2Config”；

2）通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

3）再通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，我们可以采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

1. @Configuration  

2. @EnableSwagger2  

3. **public** **class** Swagger2Config {  

4.   

5.   @Bean  

6.   **public** Docket createRestApi() {  

7.     **return** **new** Docket(DocumentationType.SWAGGER_2)  

8.             .apiInfo(apiInfo())  

9.             .select()  

10.             .apis(RequestHandlerSelectors.basePackage("com.chinamobile.cmss.bdoc.controller"))  

11.             //.apis(RequestHandlerSelectors.basePackage("com.chinamobile.cmss.bdoc.bean"))  

12.             .paths(PathSelectors.any())  

13.             .build();  

14.   }  

15.   

16. **private** ApiInfo apiInfo() {  

17.   Contact contact = **new** Contact("LIAOJIANYA","","[email protected]");  

18.   **return** **new** ApiInfoBuilder()  

19.           .title("bc-bdoc-cmh-plugin插件包内的RESTful APIs")  

20.           .description("basePath: /cmh/v1/")  

21.           .contact(contact)  

22.           .version("0.1")

23.    .license("LICENSE-CMSS")

24.            .licenseUrl("http://10.254.2.95/licenses/LICENSE-CMSS.txt")

25.           .build();  

26. }  

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

3.1 写法1：new ApiInfo

image.png

3.2 写法2：new ApiInfoBuilder

image.png