如何通过注解方式给项目添加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闪