如何通过注解方式给项目添加Swagger功能

　　在Java后端，每次开发一个新的接口后需要自测，此时可以借助Swagger功能很好地完成自测，下面将通过注解的方式来添加Swagger。

　　（1）代码部分

 1 package com.bien.edge;
 2 
 3 import java.util.ArrayList;
 4 import java.util.List;
 5 import org.springframework.context.annotation.Bean;
 6 import org.springframework.context.annotation.Configuration;
 7 import springfox.documentation.builders.ApiInfoBuilder;
 8 import springfox.documentation.builders.ParameterBuilder;
 9 import springfox.documentation.builders.PathSelectors;
10 import springfox.documentation.builders.RequestHandlerSelectors;
11 import springfox.documentation.schema.ModelRef;
12 import springfox.documentation.service.ApiInfo;
13 import springfox.documentation.service.Parameter;
14 import springfox.documentation.spi.DocumentationType;
15 import springfox.documentation.spring.web.plugins.Docket;
16 import springfox.documentation.swagger2.annotations.EnableSwagger2;
17 
18 @Configuration
19 @EnableSwagger2
20 public class Swagger2 {
21 
22     @Bean
23     public Docket createRestApi() {
24         ParameterBuilder userid = new ParameterBuilder();
25         ParameterBuilder username = new ParameterBuilder();
26         ParameterBuilder lang = new ParameterBuilder();
27         List<Parameter> pars = new ArrayList<Parameter>();
28         
29         // 添加默认请求头
30         userid.name("X-Person-No").description("人员号码").modelRef(new ModelRef("string")).parameterType("header").required(false);
31         username.name("X-Person-Name").description("人员姓名").modelRef(new ModelRef("string")).parameterType("header").required(false);
32         lang.name("X-Lang-Id").description("语言标准编码").modelRef(new ModelRef("string")).parameterType("header").required(false).defaultValue("zh_CN");
33         
34         pars.add(userid.build());
35         pars.add(username.build());
36         pars.add(lang.build());
37         return new Docket(DocumentationType.SWAGGER_2)
38                 .apiInfo(apiInfo())
39                 .select()
40                 .apis(RequestHandlerSelectors.basePackage("com.bien.edge"))
41                 .paths(PathSelectors.any())
42                 .build().globalOperationParameters(pars);
43 
44     }
45 
46     private ApiInfo apiInfo() {
47         return new ApiInfoBuilder()
48                 .title("Bien94Edge项目API可视化")
49                 .description("Bien94Edge项目API可视化相关接口")
50                 .version("1.0")
51                 .build();
52     }
53 }

　　（2）配置部分

　　在application.yml文件中配置swagger的api访问方式，如下图所示：　　

　　其实，也可以不用配置这些属性的，默认是api-docs，当前path值也可以设置为其它值，只要不与工程中其它路径冲突即可，也就是说保持唯一性即可。

　　默认时，链接类似于这样的：http://localhost:1994/bien-edge/v2/api-docs

　　若path设置为/swagger.json时，链接类似于这样的： http://localhost:1994/bien-edge/swagger.json

　　若path设置为/swaggerbien时，链接类似于这样的： http://localhost:1994/bien-edge/swaggerbien

　　（3）效果部分

　　上图是运行swagger后展示的一些相关说明信息，在上述代码中apiInfo()函数进行设置即可。

　　上图所展示的是每个接口的默认请求头信息，可以根据需要进行添加，并且还可以设置必须和非必须属性。

　　到此，项目中的Swagger功能添加完毕，是不是很简单呀。^-^

　　（4）其它

　　当访问swagger时，会有如下这些servlet path：

/
/swager-ui.html
/swagger-resources
/swagger-resources/configuration/ui
/swagger-resources/configuration
/swagger-resources/configuration/security
/error
/csrf
/webjars/springfox-swagger-ui/fonts/source-code-pro-v7-latin-600.woff2
/webjars/springfox-swagger-ui/fonts/titillium-web-v6-latin-regular.woff2
/webjars/springfox-swagger-ui/swagger-ui-bundle.js
/webjars/springfox-swagger-ui/springfox.js
/webjars/springfox-swagger-ui/swagger-ui.css
/webjars/springfox-swagger-ui/swagger-ui-standalone-preset.js
/webjars/springfox-swagger-ui/springfox.css
/webjars/springfox-swagger-ui/favicon-32x32.png
/webjars/springfox-swagger-ui/favicon-16x16.png

　　若是后端API添加了拦截器，那么访问swagger的时候可能会访问不了，此时就需要在拦截器中排除swagger的路径就可以正常访问了。只要排除这三个路径就可以了：/swagger-ui.html、/swagger-resources/**和/webjars/springfox-swagger-ui/**

------20191231闪