如何通過注解方式給項目添加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閃