springMVC整合swagger2來輸出介面文件

當前框架SpringMvc:
備註：在spring載入時應去掉config這個新增類的載入，只讓springmvc載入即可：
<context:component-scan base-package=“專案包路徑”>
<context:exclude-filter type=“assignable” expression=“新增的.SwaggerConfig”/>
</context:component-scan>
且需要再springmvc中加上配置：
<!-- swagger靜態檔案路徑 -這個路徑實在jar包中的，不用管即可->
<mvc:resources mapping=“swagger-ui.html” location=“classpath:/META-INF/resources/” />
<mvc:resources mapping="/webjars/**" location=“classpath:/META-INF/resources/webjars/” />
步驟：
一：準備相關jar包：

<!-- jackson-databind -->
  <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.9.5</version>
    </dependency>

    <!-- jackson-core -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-core</artifactId>
        <version>2.9.5</version>
    </dependency>

    <!-- jackson-annotations -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-annotations</artifactId>
        <version>2.9.5</version>
    </dependency>

    <dependency>
        <groupId>com.fasterxml.jackson.module</groupId>
        <artifactId>jackson-module-jaxb-annotations</artifactId>
        <version>2.9.5</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
        <exclusions>
            <exclusion>
                <artifactId>guava</artifactId>
                <groupId>com.google.guava</groupId>
            </exclusion>
        </exclusions>
    </dependency>

    <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>com.google.guava</groupId>
        <artifactId>guava</artifactId>
        <version>28.0-jre</version>
    </dependency>
    <!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>

    <dependency>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctorj-pdf</artifactId>
        <version>1.5.0-alpha.10.1</version>
        <scope>test</scope>
    </dependency>
  //  外掛配置：
    <plugin>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>1.5.6</version>
            <configuration>
                <!--上一步生成的asciidoc檔案路徑-->
                <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                <!--HTML生成路徑-->
                <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                <headerFooter>true</headerFooter>
                <doctype>book</doctype>
                <backend>html</backend>
                <sourceHighlighter>coderay</sourceHighlighter>
                <attributes>
                    <!--選單欄在左邊-->
                    <toc>left</toc>
                    <!--多標題排列-->
                    <toclevels>3</toclevels>
                    <!--自動打數字序號-->
                    <sectnums>true</sectnums>
                </attributes>
            </configuration>
        </plugin>

        <plugin>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>1.3.1</version>
            <configuration>
                <swaggerInput>http://localhost:8083/app/v2/api-docs</swaggerInput>
                <outputDir>src/docs/asciidoc/generated</outputDir>
                <config>
                    <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                </config>
            </configuration>
        </plugin>

二：新增配置類以及方法：

@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
//                .ignoredParameterTypes(query)
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))  //只顯示新增@Api註解的類
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("中歐班列APP介面API")  //粗標題
                .description("中歐班列APP介面API")   //描述
                .version("2.0.1")   //api version
                .termsOfServiceUrl("http://localhost:8084/app/swagger-ui.html")
                .license("中歐班列介面文件")   //連結名稱
                .licenseUrl("http://localhost:8084/app/swagger-ui.html")   //連結地址
                .build();
    }
}

第三步：在自己專案介面裡加入註解
@Controller
@Api(description = “支付類”, tags=“支付標籤”)

public class PayController extends BaseController {
 /**
     * 跳轉到支付確認頁面前校驗
     * @param data orderNo  訂單編號
     * @return
     */
    @ApiOperation(value = "支付校驗", notes="支付校驗相關引數，以及定價", httpMethod = "POST")
    @ApiImplicitParams({ @ApiImplicitParam(name = "data", value = "引數進行加密，json串{orderNo:orderNo}", dataType = "String", paramType = "query", required = true)})
    @ApiResponses({
            @ApiResponse(code=000,message="成功"),
            @ApiResponse(code=999,message="失敗")
    })
    @RequestMapping("app/toPayConfirmCheck")
    @ResponseBody
    public Map<String, Object> toPayConfirmCheck(@RequestParam String data, @ApiIgnore HttpSession session) {

    }
}

此時啟動專案：http://localhost:8080/name/swagger-ui.html即可看到專案介面文件（線上）

第四步：將文件匯出來成xml
增加測試方法：

public class SwaggerTest {
    public void generateAsciiDocs() throws Exception {
        //    輸出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .withOutputLanguage(Language.ZH)
                .withPathsGroupedBy(GroupBy.TAGS)
                .withGeneratedExamples()
                .withoutInlineSchema()
                .withFlatBody()
                .build();
        Swagger2MarkupConverter.from(new URL("http://localhost:8084/app/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("E:\\svn\\01-程式碼\\trunk\\crexpress-parent\\crexpress-mobile\\src\\docs\\asciidoc\\generated\\api"));
    }
//    public void generatePDF() {
//        //樣式
//        String style = "pdf-style=E:\\themes\\theme.yml";
//        //字型
//        String fontsdir = "pdf-fontsdir=E:\\fonts";
//        //需要指定adoc檔案位置
//        String adocPath = "E:\\all.adoc";
        AsciidoctorInvoker.main(new String[]{"-a",style,"-a",fontsdir,"-b","pdf",adocPath});
//    }

    pubic static void main(String[] args) {
        SwaggerTest test = new SwaggerTest();
        try {
            test.generateAsciiDocs();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

此時就會在
E:\svn\01-程式碼\trunk\crexpress-parent\crexpress-mobile\src\docs\asciidoc\generated\api這個路徑下生成api.adoc檔案。
然後

命令列：asciidoctor:process-asciidoc
然後待生成api.adoc檔案後執行此maven就可以生成靜態html介面文件了。

swagger2 註解整體說明
複製程式碼
@Api：用在請求的類上，表示對類的說明
tags=“說明該類的作用，可以在UI介面上看到的註解”
value=“該引數沒什麼意義，在UI介面上也看到，所以不需要配置”

@ApiOperation：用在請求的方法上，說明方法的用途、作用
value=“說明方法的用途、作用”
notes=“方法的備註說明”

@ApiImplicitParams：用在請求的方法上，表示一組引數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
name：引數名
value：引數的漢字說明、解釋
required：引數是否必須傳
paramType：引數放在哪個地方
· header --> 請求引數的獲取：@RequestHeader
· query --> 請求引數的獲取：@RequestParam
· path（用於restful介面）–> 請求引數的獲取：@PathVariable
· body（不常用）
· form（不常用）
dataType：引數型別，預設String，其它值dataType=“Integer”
defaultValue：引數的預設值

@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
code：數字，例如400
message：資訊，例如"請求引數沒填好"
response：丟擲異常的類

@ApiModel：用於響應類上，表示一個返回響應資料的資訊
（這種一般用在post建立的時候，使用@RequestBody這樣的場景，
請求引數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
複製程式碼

1. @Api：用在請求的類上，說明該類的作用

@Api：用在請求的類上，說明該類的作用
tags=“說明該類的作用”
value=“該引數沒什麼意義，所以不需要配置”
示例
@Api(tags=“APP使用者註冊Controller”)

2. @ApiOperation：用在請求的方法上，說明方法的作用

@ApiOperation：“用在請求的方法上，說明方法的作用”
value=“說明方法的作用”
notes=“方法的備註說明”
示例
@ApiOperation(value=“使用者註冊”,notes=“手機號、密碼都是必輸項，年齡隨邊填，但必須是數字”)

3. @ApiImplicitParams：用在請求的方法上，包含一組引數說明

複製程式碼
@ApiImplicitParams：用在請求的方法上，包含一組引數說明
@ApiImplicitParam：用在 @ApiImplicitParams 註解中，指定一個請求引數的配置資訊
name：引數名
value：引數的漢字說明、解釋
required：引數是否必須傳
paramType：引數放在哪個地方
· header --> 請求引數的獲取：@RequestHeader
· query --> 請求引數的獲取：@RequestParam
· path（用於restful介面）–> 請求引數的獲取：@PathVariable
· body（不常用）
· form（不常用）
dataType：引數型別，預設String，其它值dataType=“Integer”
defaultValue：引數的預設值
複製程式碼

示例

@ApiImplicitParams({
@ApiImplicitParam(name=“mobile”,value=“手機號”,required=true,paramType=“form”),
@ApiImplicitParam(name=“password”,value=“密碼”,required=true,paramType=“form”),
@ApiImplicitParam(name=“age”,value=“年齡”,required=true,paramType=“form”,dataType=“Integer”)
})
4. @ApiResponses：用於請求的方法上，表示一組響應

@ApiResponses：用於請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
code：數字，例如400
message：資訊，例如"請求引數沒填好"
response：丟擲異常的類

示例

@ApiOperation(value = “select1請求”,notes = “多個引數，多種的查詢引數型別”)
@ApiResponses({
@ApiResponse(code=400,message=“請求引數沒填好”),
@ApiResponse(code=404,message=“請求路徑沒有或頁面跳轉路徑不對”)
})
5. @ApiModel：用於響應類上，表示一個返回響應資料的資訊
ApiModel：用於響應類上，表示一個返回響應資料的資訊
（這種一般用在post建立的時候，使用@RequestBody這樣的場景，
請求引數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
示例

複製程式碼
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

@ApiModel(description= “返回響應資料”)
public class RestMessage implements Serializable{

@ApiModelProperty(value = "是否成功")
private boolean success=true;
@ApiModelProperty(value = "返回物件")
private Object data;
@ApiModelProperty(value = "錯誤編號")
private Integer errCode;
@ApiModelProperty(value = "錯誤資訊")
private String message;

/* getter/setter */

}