springboot集成swagger

1、概要

　　Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。

2、詳細步驟

　　1.添加maven依賴

 <!--引入swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.20</version>
            <exclusions>
                <exclusion>
                    <groupId>com.fasterxml.jackson.core</groupId>
                    <artifactId>jackson-annotations</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

　　2.在pom中添加插件

　　　　　　<plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.14.1</version>
                <configuration>
                    <systemPropertyVariables>
                        <io.springfox.staticdocs.outputDir>${project.build.directory}/swagger/api/1.3.0</io.springfox.staticdocs.outputDir>
                        <io.swagger.json.uris>/v2/api-docs?group=api</io.swagger.json.uris>
                        <io.swagger.json.output.name>swagger-pai-v1.json</io.swagger.json.output.name>
                    </systemPropertyVariables>
                    <argLine>-Xmx256M -XX:MaxPermSize=128M</argLine>
                    <parallel>false</parallel>
                    <testFailureIgnore>true</testFailureIgnore>
                    <includes>
                        <include>**/*.java</include>
                    </includes>
                </configuration>
            </plugin>

3、添加配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .globalOperationParameters(setHeaderToken())　//若是使用到了token，這裏加入token設置
                .apiInfo(apiInfo())
                .groupName("api")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.web.api")) //api接口目錄
                .paths(PathSelectors.any())
                .build();
    }

    private List<Parameter> setHeaderToken() {
        ParameterBuilder tokenPra = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPra.name("Token").description("接口校驗令牌").modelRef(new ModelRef("string")).defaultValue(TokenUtils.get()).parameterType("header")
                .required(true).build();
        pars.add(tokenPra.build());

        return pars;
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("小明", "", "xiaoming@qq.com");

        return new ApiInfoBuilder().version("1.3").title("swagger測試接口").description("swagger測試接口").contact(contact).license("") .licenseUrl("http://www.qq.com").build(); } 
}

SwaggerConfig 類可隨意放在代碼的目錄中，加入這些配置後，啓動springboot項目，訪問 http://localhost:8080/swaggerDemo/swagger-ui.html  ，其中swaggerDemo是項目的上下文，若是配置了不用上下文，也能夠直接

http://localhost:8080/swagger-ui.html 進行啓動，swagger的json路徑爲：http://localhost:8080/swaggerDemo/v2/api-docs?group=api，能夠看到完整路徑

4、生成swagger.json文件
編寫測試類，在mvn install的時候能夠將swagger.json生成到你在plugin配置的路徑中

@WebAppConfiguration
//// 讓 JUnit 運行 Spring 的測試環境， 得到 Spring 環境的上下文的支持
@RunWith(SpringRunner.class)
//// 獲取啓動類，加載配置，肯定裝載 Spring 程序的裝載方法，它回去尋找 主配置啓動類（被 @SpringBootApplication 註解的）
@SpringBootTest
public class SwaggerTest {

    @Autowired
    private WebApplicationContext wac;

    private MockMvc mockMvc;


    @Before
    public void setup(){
        //init applicationContext
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.wac).build();
    }

    @Test
    public void getSwaggerJson() throws Exception{
        //獲取插件中配置的swagger文件輸出地址
        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
        //獲取插件中配置的swagger.json的訪問地址,有幾個接口分組就有幾個訪問地址，地址必須是swagger2controller中原生的，若是是在web.xml自定義的則沒法訪問，由於mock的服務不會解析web.xml
        String uris = System.getProperty("io.swagger.json.uris");
        //獲取插件中配置的每一個json文件的名稱，名稱可配置多個，有幾個接口分組就有幾個名稱， 名稱的格式必須是：組件標識-接口分組標識-接口版本號，例如：swagger-api-v1
        String swaggerOutName = System.getProperty("io.swagger.json.output.name");
        String[] uriArray = uris.trim().split(",");
        String[] swaggerOutNameArray = swaggerOutName.trim().split(",");

        for (int i = 0; i < uriArray.length; i++){
            MvcResult mvcResult = this.mockMvc
                    .perform((MockMvcRequestBuilders.get(uriArray[i])) // 測試的相對地址
                            .accept(MediaType.APPLICATION_JSON_UTF8)) // accept response content type
                    .andExpect(MockMvcResultMatchers.status().isOk())  // 期待返回狀態嗎碼200
                    .andReturn();

            MockHttpServletResponse response = mvcResult.getResponse();
            String swaggerJson = response.getContentAsString();
            Files.createDirectories(Paths.get(outputDir));
            try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, swaggerOutNameArray[i]), StandardCharsets.UTF_8)){
                writer.write(swaggerJson);
            }
        }

    }
}

這樣生成的json文件就會在項目的target目錄的/swagger/api/1.3.0下，名字叫 swagger-pai-v1.json，路徑及文件名都是在plugin中配置的