swagger2

什麼是swagger2

• swagger是一個restful接口的文檔自動生成和功能測試的框架
• swagger是一個規範和完整的框架，用於生成、描述、調用和可視化restful風格的web服務
• 編寫和維護接口文檔是每個程序員的職責，根據Swagger2可以快速幫助我們編寫最新的API接口文檔，再也不用擔心開會前仍忙於整理各種資料了，間接提升了團隊開發的溝通效率。

常用註解

swagger通過註解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數描述
• @ApiModel：用對象來接收參數
• @ApiProperty：用對象接收參數時，描述對象的一個字段
• @ApiResponse：HTTP響應其中1個描述
• @ApiResponses：HTTP響應整體描述
• @ApiIgnore：使用該註解忽略這個API
• @ApiError ：發生錯誤返回的信息
• @ApiImplicitParam：一個請求參數
• @ApiImplicitParams：多個請求參數

springboot整合swagger2

第一步：導入pom

<!-- Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- END Swagger -->

第二步、SwaggerConfig.java中配置接口文檔基本信息和啓動swagger2支持

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("hello"))
            .paths(PathSelectors.any())
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Spring Boot中使用Swagger2構建RESTful APIs")
            .description("歡迎來****社區學習")
            .termsOfServiceUrl("http://********.com/")
            .version("1.0")
            .build();
    }

}

導出wagger2文檔

<!-- 生成接口文檔 -->
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>

插件生成文檔

<!--第一步-->
<!--mvn swagger2markup:convertSwagger2markup-->
<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputFile>src/docs/asciidoc/generated/v2-api-doc</outputFile>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

<!--第二步-->
<!--mvn asciidoctor:process-asciidoc-->
<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
        </attributes>
    </configuration>
</plugin>