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

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

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

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

一、接口文檔的痛點

①、準確性

　　傳統的接口文檔產出，基本上是由後端人員進行手工編寫，在編寫文檔過程當中，極可能會因爲人爲的粗枝大葉，形成接口文檔某個字段，或者某個接口名寫錯，那麼這些粗心致使的錯誤就會影響後續的聯調等操做。

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

②、實時性

　　在項目開發過程當中，當後端人員提供了一份接口文檔，而且與前端人員聯調也經過了，可是因爲需求變動，致使後端接口發生了變化，然後端人員有可能懶，又沒有實時的去更新接口文檔，那麼前端人員就沒法根據最新的接口文檔進行修改，從而沒法有效的完成整個項目的需求變動。

　　因此接口文檔的實時性也是很重要的。

③、詳細性

　　在進行接口文檔編寫時，基本上都會有一個標準，包括接口名、方法類型、入參、入參類型，返回值，返回值的各類狀況說明等等。通常公司都會經過接口文檔規範來強制你們按照要求編寫，可是理想很美好，現實很殘酷。隨着時間推移，項目迭代次數過多，或者項目週期趕等等因素，你們很難可以徹底按照規範來編寫接口文檔。

　　因爲接口文檔的不夠規範，描述不夠詳細，對於接口文檔的需求方會形成困擾。

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

　　1、自動生成知足接口規範的文檔

　　2、可以跟隨代碼實時更新

　　那麼應該怎麼辦呢？

二、Swagger

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

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

　　這裏，咱們不對 Swagger 進行過多的描述，須要瞭解更多的，能夠參考下面的官方文檔。

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

三、普通版工具-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倉庫中選取最新的版本。　　

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

②、編寫配置文件

 1 package com.ys.swaggerbootstrapuidemo.common;
 2 
 3 import org.springframework.beans.factory.annotation.Value;
 4 import org.springframework.context.annotation.Bean;
 5 import org.springframework.context.annotation.Configuration;
 6 import springfox.documentation.builders.ApiInfoBuilder;
 7 import springfox.documentation.builders.PathSelectors;
 8 import springfox.documentation.builders.RequestHandlerSelectors;
 9 import springfox.documentation.service.ApiInfo;
10 import springfox.documentation.service.Contact;
11 import springfox.documentation.spi.DocumentationType;
12 import springfox.documentation.spring.web.plugins.Docket;
13 import springfox.documentation.swagger2.annotations.EnableSwagger2;
14 
15 /**
16  * @Author: yuShuai
17  * @Description: Swagger2的接口配置
18  * @Date: 2019/10/8 13:41
19  * @params:
20  * @return:
21  */
22 @Configuration
23 @EnableSwagger2
24 public class SwaggerConfig {
25 
26 
27     @Value("${config.swaggerConfig.isShow}")
28     private Boolean isShow;
29 
30 
31     @Bean
32     public Docket createUserRestApi() {
33         return new Docket(DocumentationType.SWAGGER_2)
34                 .enable(isShow)
35                 // 用來建立該API的基本信息，展現在文檔的頁面中（自定義展現的信息）
36                 .apiInfo(apiInfo())
37                 .groupName("用戶管理API")
38                 // 經過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展示
39                 .select()
40                 .apis(RequestHandlerSelectors.basePackage("com.ys.swaggerbootstrapuidemo.controller.user"))
41                 // 掃描全部有註解的api
42                 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
43                 // 掃描指定包中的swagger註解
44                 //.apis(RequestHandlerSelectors.basePackage("com.kxjl.belleps.api"))
45                 // 掃描全部 .apis(RequestHandlerSelectors.any())
46                 // 對全部路徑進行監控
47                 .paths(PathSelectors.any())
48                 .build();
49     }
50 
51     @Bean
52     public Docket createRoleRestApi() {
53         return new Docket(DocumentationType.SWAGGER_2)
54                 .enable(isShow)
55                 // 用來建立該API的基本信息，展現在文檔的頁面中（自定義展現的信息）
56                 .apiInfo(apiInfo())
57                 .groupName("角色管理API")
58                 // 經過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展示
59                 .select()
60                 .apis(RequestHandlerSelectors.basePackage("com.ys.swaggerbootstrapuidemo.controller.role"))
61                 // 掃描全部有註解的api
62                 //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
63                 // 掃描指定包中的swagger註解
64                 //.apis(RequestHandlerSelectors.basePackage("com.kxjl.belleps.api"))
65                 // 掃描全部 .apis(RequestHandlerSelectors.any())
66                 // 對全部路徑進行監控
67                 .paths(PathSelectors.any())
68                 .build();
69     }
70 
71     /**
72      * 添加摘要信息
73      */
74     private ApiInfo apiInfo() {
75         // 用ApiInfoBuilder進行定製
76         return new ApiInfoBuilder()
77                 // 設置標題
78                 .title("標題：Swagger測試_接口文檔")
79                 // 描述
80                 .description("描述：Swagger測試相關接口信息")
81                 // 做者信息
82                 .contact(new Contact("ShuaiYu", "https://www.cnblogs.com/ysocean/", "1827165732@163.com"))
83                 // 版本
84                 .version("版本號:" + "1.0")
85                 .build();
86     }
87 }

View Code

　　PS:相關配置的意思在代碼中都有標註，這裏須要注意如下兩點：

　　1、因爲swagger是用於生成API文檔，那麼在生成環境中是不能讓別人可以訪問的，須要須要配置 new Docket(DocumentationType.SWAGGER_2).enable(isShow)。

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

　　applicaion.yml 文件配置：

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

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

③、訪問地址

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

　　PS:這裏的「項目訪問地址名稱」是你在配置文件配置了就寫，沒有配置，這裏則沒有。好比，本項目的配置文件爲：

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

　　那麼訪問接口文檔的路徑爲：

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

④、截圖展現

1、初始界面

 

 

2、 配置了多個groupName()屬性，展現以下

 

 3、接口詳情

 

 

具體能夠直接運行最前文的 github 項目，查看便可。

四、加強版工具-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 

 五、總結

　　你們在使用過程當中，直接用加強版工具 swagger-bootstrap-ui  就能夠了。再次列一下我寫的一個 demo 路徑：

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

　　這是一個 Springboot 項目，你們能夠下載，直接運行，有不懂的歡迎留言評論。

　　本文已獨家受權給腳本之家（jb51net）公衆號發佈!!!