背景

• 服務端開發同學需要花很多時間編寫和維護大量的Rest介面文件，且往往介面修改後沒有及時同步文件，讓對接方和後續維護者一頭霧水。
• 有沒有一種方式可以相對容易地生成可讀性好的Rest文件，並且做到與程式碼同步？

目標

• 通過Swagger註釋自動生成Rest文件介面。
• 通過Swagger2Markup生成靜態文件（html/markdown/wiki）

使用Swagger註解自動生成Rest文件介面

maven引入Swagger依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId
 
>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

配置Swagger

@SpringBootApplication
@EnableSwagger2
public class AppStarter extends WebMvcConfigurerAdapter {

    public static void main(String[] args) {
        SpringApplication.run(AppStarter.class, args);
    }

    /**
     * 建立Rest Api描述
     * @return
 

     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()                       //按條件指定生成文件介面
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 介面描述
     * @return
 

     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("測試專案")
                .description("User實體CRUD")
                .version("1.0")
                .build();
    }
}

• EnableSwagger2啟動Swagger
• 建立Docket

使用Swagger註解

controller註解

@RestController
@RequestMapping("/v1/users")
@Api(description = "使用者管理介面")
public class UserController {

    @PostMapping
    @ApiOperation("建立使用者")
    public void addUser(@RequestBody User user){

    }

    @GetMapping
    @ApiOperation("查詢使用者")
    public List<User> getUsers(@ApiParam(value = "模糊查詢使用者名稱") String name){
        return Lists.newArrayList(
                User.builder().id(1).name("test-name1").birth(new Date()).build(),
                User.builder().id(2).name("test-name2").birth(new Date()).build()
        );
    }

    @GetMapping("/{id}")
    @ApiOperation("獲取使用者")
    public User getUser(@ApiParam(value = "使用者ID") @PathVariable long id){
        return User.builder().id(id).name("test-name").birth(new Date()).build();
    }

    @PutMapping("/{id}")
    @ApiOperation("修改使用者")
    public void updateUser(@ApiParam(value = "使用者ID") @PathVariable long id,
                           @RequestBody User user){
    }

    @DeleteMapping("/{id}")
    @ApiOperation("刪除使用者")
    public void deleteUser(@ApiParam(value = "使用者ID") @PathVariable long id){
    }
}

實體註解

@ApiModel("使用者")
public class User {

    @ApiModelProperty("使用者ID")
    private long id;

    @ApiModelProperty("使用者名稱")
    private String name;

    @ApiModelProperty("生日")
    private Date birth;
}

生成api-docs

• 打好註解後，編譯，啟動專案。
• swagger會在springmvc中建立 GET http://host:port/v2/api-docs 介面，輸出json格式的rest api文件

使用Swagger2Markup生成靜態文件

• 有了swagger的文件api，需要將其生成可讀的文字文件（html/markdown/wiki），並靜態化。

啟動專案

• 將寫好註解的專案啟動，並保證/v2/api-docs介面可以訪問。

配置swagger2markup外掛

• maven.build.plugins增加swagger2markup外掛

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.1</version>
    <configuration>
        <!-- api-docs訪問url -->
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <!-- 生成為單個文件，輸出路徑 -->
        <outputFile>src/docs/asciidoc/generated/all</outputFile>
        <!-- 生成為多個文件，輸出路徑 -->
        <!--<outputDir>src/docs/asciidoc/generated</outputDir>-->
        <config>
            <!-- wiki格式文件 -->
            <swagger2markup.markupLanguage>CONFLUENCE_MARKUP</swagger2markup.markupLanguage>

            <!-- ascii格式文件 -->
            <!--<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>-->

            <!-- markdown格式文件 -->
            <!--<swagger2markup.markupLanguage>MARKDOWN</swagger2markup.markupLanguage>-->
            <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
        </config>
    </configuration>
</plugin>

執行swagger2markup外掛

• mvn命令執行swagger2markup:convertSwagger2markup
• 在專案的/src/docs/asciidoc/generated中找到結果檔案

處理結果檔案

CONFLUENCE_MARKUP（wiki）

• confluence的wiki支援此格式

• 使用插入”wiki標記“

  
  

• 選擇“企業維基”，將內容複製進去

  
  

MARKDOWN

• 可用在任何支援markdown的編輯器中

ASCIIDOC（html）

• ascii文件，可以再進一步將其轉換為可讀性優秀的html文件

配置asciidoctor外掛

• maven.build.plugins中增加配置

<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>

        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>

        <!-- html文件格式引數 -->
        <attributes>
            <doctype>book</doctype>
            <toc>left</toc>
            <toclevels>3</toclevels>
            <numbered></numbered>
            <hardbreaks></hardbreaks>
            <sectlinks></sectlinks>
            <sectanchors></sectanchors>
        </attributes>
    </configuration>
</plugin>

執行asciidoctor外掛