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

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

　　（1）代码部分

 package com.bien.edge;

 import java.util.ArrayList;
 import java.util.List;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import springfox.documentation.builders.ApiInfoBuilder;
 import springfox.documentation.builders.ParameterBuilder;
 import springfox.documentation.builders.PathSelectors;
 import springfox.documentation.builders.RequestHandlerSelectors;
 import springfox.documentation.schema.ModelRef;
 import springfox.documentation.service.ApiInfo;
 import springfox.documentation.service.Parameter;
 import springfox.documentation.spi.DocumentationType;
 import springfox.documentation.spring.web.plugins.Docket;
 import springfox.documentation.swagger2.annotations.EnableSwagger2;

 @Configuration
 @EnableSwagger2
 public class Swagger2 {

     @Bean
     public Docket createRestApi() {
         ParameterBuilder userid = new ParameterBuilder();
         ParameterBuilder username = new ParameterBuilder();
         ParameterBuilder lang = new ParameterBuilder();
         List<Parameter> pars = new ArrayList<Parameter>();

         // 添加默认请求头
         userid.name("X-Person-No").description("人员号码").modelRef(new ModelRef("string")).parameterType("header").required(false);
         username.name("X-Person-Name").description("人员姓名").modelRef(new ModelRef("string")).parameterType("header").required(false);
         lang.name("X-Lang-Id").description("语言标准编码").modelRef(new ModelRef("string")).parameterType("header").required(false).defaultValue("zh_CN");

         pars.add(userid.build());
         pars.add(username.build());
         pars.add(lang.build());
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.bien.edge"))
                 .paths(PathSelectors.any())
                 .build().globalOperationParameters(pars);

     }

     private ApiInfo apiInfo() {
         return new ApiInfoBuilder()
                 .title("Bien94Edge项目API可视化")
                 .description("Bien94Edge项目API可视化相关接口")
                 .version("1.0")
                 .build();
     }
 }

　　（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闪