如何優雅的生成接口文檔？

　　我們知道在項目開發階段，接口文檔基本上是必備產物了，一般由后端開發人員提供，作為和前端人員進行前后端接口聯調的橋梁，或者與別的項目模塊進行交互提供指導等等，接口文檔的准確性，實時性，詳細與否等，都會極大的影響前面的操作。那么如何才能優雅的生成接口文檔呢？

　　這里，我首先給出如何生成接口文檔的小demo地址，在下面介紹中，有不懂的，可以參考項目注釋來看。

https://github.com/YSOcean/swagger-bootstrap-ui-demo.git

1、接口文檔的痛點

①、准確性

　　傳統的接口文檔產出，基本上是由后端人員進行手工編寫，在編寫文檔過程中，很可能會由於人為的粗心大意，造成接口文檔某個字段，或者某個接口名寫錯，那么這些粗心導致的錯誤就會影響后續的聯調等操作。

　　所以接口文檔和實際代碼的一致性是比較重要的。

②、實時性

　　在項目開發過程中，當后端人員提供了一份接口文檔，並且與前端人員聯調也通過了，但是由於需求變更，導致后端接口發生了變化，而后端人員有可能懶，又沒有實時的去更新接口文檔，那么前端人員就無法根據最新的接口文檔進行修改，從而無法有效的完成整個項目的需求變更。

　　所以接口文檔的實時性也是很重要的。

③、詳細性

　　在進行接口文檔編寫時，基本上都會有一個標准，包括接口名、方法類型、入參、入參類型，返回值，返回值的各種情況說明等等。一般公司都會通過接口文檔規范來強制大家按照要求編寫，但是理想很美好，現實很殘酷。隨着時間推移，項目迭代次數過多，或者項目周期趕等等因素，大家很難能夠完全按照規范來編寫接口文檔。

　　由於接口文檔的不夠規范，描述不夠詳細，對於接口文檔的需求方會造成困擾。

　　以上便是關於接口文檔的一些痛點，可能你就會開始想，優雅的接口文檔，應該滿足如下特性：

　　一、自動生成滿足接口規范的文檔

　　二、能夠跟隨代碼實時更新

　　那么應該怎么辦呢？

2、Swagger

　　程序員是萬能的，基本上有痛點，就會有解決方案。於是 Swagger 產生了。

　　簡單來說，Swagger 是一套規范，只需要按照它的規范去定義接口以及接口相關信息，在通過Swagger衍生出來的一系列項目和工具，就可以做到生成各種格式的接口文檔，生成多種語言的客戶端和服務端的代碼，以及在線接口調試頁面等等。這樣，如果按照新的開發模式，在開發新版本或者迭代版本的時候，只需要更新Swagger描述文件，就可以自動生成接口文檔和客戶端服務端代碼，做到調用端代碼、服務端代碼以及接口文檔的一致性。

　　這里，我們不對 Swagger 進行過多的描述，需要了解更多的，可以參考下面的官方文檔。

　　Swagger 官方網站：https://swagger.io/

3、普通版工具-springfox-swagger-ui

　　多的不說，我們直接進入正題，如何在項目中引入swagger呢？

①、引入jar包

<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<!--swagger2-UI-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

　　PS：這里的版本號可以參考源碼pom.xml文件。或者到下面的Maven倉庫中選取最新的版本。　　

　　一、swagger2倉庫地址：https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
　　二、springfox-swagger-ui倉庫地址：https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

②、編寫配置文件

package com.ys.swaggerbootstrapuidemo.common;

import org.springframework.beans.factory.annotation.Value;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author: yuShuai
 * @Description: Swagger2的接口配置
 * @Date: 2019/10/8 13:41
 * @params:
 * @return:
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {


    @Value("${config.swaggerConfig.isShow}")
    private Boolean isShow;


    @Bean
    public Docket createUserRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(isShow)
                // 用來創建該API的基本信息，展示在文檔的頁面中（自定義展示的信息）
                .apiInfo(apiInfo())
                .groupName("用戶管理API")
                // 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ys.swaggerbootstrapuidemo.controller.user"))
                // 掃描所有有注解的api
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 掃描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.kxjl.belleps.api"))
                // 掃描所有 .apis(RequestHandlerSelectors.any())
                // 對所有路徑進行監控
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createRoleRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(isShow)
                // 用來創建該API的基本信息，展示在文檔的頁面中（自定義展示的信息）
                .apiInfo(apiInfo())
                .groupName("角色管理API")
                // 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ys.swaggerbootstrapuidemo.controller.role"))
                // 掃描所有有注解的api
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 掃描指定包中的swagger注解
                //.apis(RequestHandlerSelectors.basePackage("com.kxjl.belleps.api"))
                // 掃描所有 .apis(RequestHandlerSelectors.any())
                // 對所有路徑進行監控
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder進行定制
        return new ApiInfoBuilder()
                // 設置標題
                .title("標題：Swagger測試_接口文檔")
                // 描述
                .description("描述：Swagger測試相關接口信息")
                // 作者信息
                .contact(new Contact("ShuaiYu", "https://www.cnblogs.com/ysocean/", "[e-mail]"))
                // 版本
                .version("版本號:" + "1.0")
                .build();
    }
}

　　PS:相關配置的意思在代碼中都有標注，這里需要注意以下兩點：

　　一、由於swagger是用於生成API文檔，那么在生成環境中是不能讓別人能夠訪問的，需要需要配置 new Docket(DocumentationType.SWAGGER_2).enable(isShow)。

　　對於isShow屬性，我們可以在application.yml配置文件進行相關設定，true表示顯示，false不是不展示。

　　applicaion.yml 文件配置：

config:
  swaggerConfig:
    #是否展示swagger,true表示展示。生產環境中需要置為false,避免暴露接口
    isShow: true

　　二、配置文件中，我配置了groupName()屬性，這是為了在微服務模式下，模塊太多，便於分類展示（具體可以看下面的截圖展示）。只保留一個Docket也是可以的。 

③、訪問地址

http://${host}:${port}/項目訪問地址名稱/swagger-ui.html

　　PS:這里的“項目訪問地址名稱”是你在配置文件配置了就寫，沒有配置，這里則沒有。比如，本項目的配置文件為：

server:
  port: 8070
  servlet:
    context-path: /swaggerTest

　　那么訪問接口文檔的路徑為：

http://localhost:8070/swaggerTest/swagger-ui.html

④、截圖展示

一、初始界面

 

 

二、 配置了多個groupName()屬性，展示如下

 

 三、接口詳情

 

 

具體可以直接運行最前文的 github 項目，查看即可。

4、增強版工具-swagger-bootstrap-ui

　　swagger-bootstrap-ui 是 springfox-swagger 的增強UI實現，為Java開發者在使用Swagger的時候，能擁有一份簡潔、強大的接口文檔體驗

　　這個項目的地址：https://github.com/xiaoymin/swagger-bootstrap-ui

　　作者對於這個項目的描述已經很清楚了。

①、用法

　　在用法上，和前面普通版工具一樣，只需要將jar包 springfox-swagger-ui 替換成 swagger-bootstrap-ui 即可。

②、訪問路徑

http://${host}:${port}/項目訪問地址名稱/doc.html

③、截圖展示

 

④、生成接口文檔 md 

 5、總結

　　大家在使用過程中，直接用增強版工具 swagger-bootstrap-ui  就可以了。再次列一下我寫的一個 demo 路徑：

https://github.com/YSOcean/swagger-bootstrap-ui-demo.git

　　這是一個 Springboot 項目，大家可以下載，直接運行，有不懂的歡迎留言評論。

　　本文已獨家授權給腳本之家（jb51net）公眾號發布!!!