Swagger
1、Swagger介绍
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。
1.1 swagger基础依赖介绍
1. <dependency>
2. <groupId>io.springfox</groupId>
3. <artifactId>springfox-swagger-ui</artifactId>
4. <version>2.6.1</version>
5. <exclusions>
6. <exclusion>
7. <artifactId>guava</artifactId>
8. <groupId>com.google.guava</groupId>
9. </exclusion>
10. </exclusions>
11. </dependency>
12. <dependency>
13. <groupId>io.swagger</groupId>
14. <artifactId>swagger-annotations</artifactId>
15. <version>1.5.4</version>
16. </dependency>
17.
18. <dependency>
19. <groupId>io.springfox</groupId>
20. <artifactId>springfox-swagger2</artifactId>
21. <version>2.6.1</version>
22. <exclusions>
23. <exclusion>
24. <artifactId>swagger-annotations</artifactId>
25. <groupId>io.swagger</groupId>
26. </exclusion>
27. <exclusion>
28. <artifactId>guava</artifactId>
29. <groupId>com.google.guava</groupId>
30. </exclusion>
31. </exclusions>
32. </dependency>
<!-- swagger begin -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<exclusions>
<exclusion>
<artifactId>guava</artifactId>
<groupId>com.google.guava</groupId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.4</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<exclusions>
<exclusion>
<artifactId>swagger-annotations</artifactId>
<groupId>io.swagger</groupId>
</exclusion>
<exclusion>
<artifactId>guava</artifactId>
<groupId>com.google.guava</groupId>
</exclusion>
</exclusions>
</dependency>
<!-- swagger end-->
springfox-swagger2是API获取的包，springfox-swagger-ui是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。
1.2 swagger-maven-plugin依赖
1. <!-- swagger-->
2. <plugin>
3. <groupId>org.apache.maven.plugins</groupId>
4. <artifactId>maven-javadoc-plugin</artifactId>
5. <configuration>
6. <charset>UTF-8</charset>
7. <docencoding>UTF-8</docencoding>
8. <failOnError>**false**</failOnError>
9. </configuration>
10. </plugin>
11. <plugin>
12. <groupId>com.github.kongchen</groupId>
13. <artifactId>swagger-maven-plugin</artifactId>
14. <version>3.1.4</version>
15. <configuration>
16. <apiSources>
17. <apiSource>
18. <springmvc>**false**</springmvc>
19. <!-- web项目Controller包名 -->
20. <locations>
21. <location>com.chinamobile.cmss.bdoc.controller</location>
22. </locations>
23. <schemes>
24. <scheme>http</scheme>
25. </schemes> <host>localhost:9098</host>
26. <basePath>/cmh/v1</basePath>
27. <info>
28. <title>bc-bdoc-cmh-plugin module rest api</title>
29. <version>v1</version>
30. <description>bc-bdoc-cmh-plugin 底层服务开通插件 REST API</description>
31. <!--<termsOfService>-->
32. <!--http://www.github.com/kongchen/swagger-maven-plugin-->
33. <!--</termsOfService>-->
34. <contact>
35. <email>liaojianya@cmss.chinamobile.com</email>
36. <name>Jianya Liao</name>
37. </contact>
38. <license>
39. <url>http://10.254.2.95/licenses/LICENSE-CMSS.txt</url>
40. <name>The CMSS Software License, Version 1.0</name>
41. </license>
42. </info>
43. <!--Support classpath or file absolute path here. 1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html" 2) file e.g: "${basedir}/src/main/resources/markdown.hbs", "${basedir}/src/main/resources/templates/hello.html"-->
44. <!--<templatePath>classpath:/templates/strapdown.html.hbs</templatePath>-->
45. <!--<outputPath>${basedir}/generated/document.md</outputPath>-->
46. <swaggerDirectory>${basedir}/target/generated/swagger-ui</swaggerDirectory>
47. <swaggerFileName>bc-bdoc-cmh-plugin</swaggerFileName>
48. </apiSource>
49. </apiSources>
50. </configuration>
51. <executions>
52. <execution>
53. <phase>compile</phase>
54. <goals>
55. <goal>generate</goal>
56. </goals>
57. </execution>
58. </executions>
59. </plugin>
其中： <locations>com.chinamobile.cmss.bdoc.controller</locations> 是配置web项目Controller中的api；
<swaggerDirectory>${basedir}/target/generated/swagger-ui</swaggerDirectory>
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","","liaojianya@cmss.chinamobile.com");
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
网友评论