springboot項目開發規範之API文檔工具swagger

API文檔工具swagger

• 1.Swagger2介紹
• 2.配置Swagger2
• • 1.pom檔案中添加依賴
  • 2.建立Swagger的配置檔案 SwaggerConfig.java
  • • 2.1.基本配置
    • 2.2.啟動服務檢視接口
• 3.分組配置及參數說明
• • 3.1.Docket類
  • 3.2.配置基本的分組資訊
• 4.定義接口說明和參數說明
• 5.定義entity實體類
• • 5.1.注解，entity的實體類中可以添加一些自定義設定
  • 5.2.解決時間格式顯示錯誤

1.Swagger2介紹

Swagger 是一款RESTFUL接口的、基于YAML、JSON語言的文檔線上自動生成、代碼自動生成的工具。前後端分離開發模式中，api文檔是最好的溝通方式。

及時性 (接口變更後，能夠及時準确地通知相關前後端開發人員)

規範性 (并且保證接口的規範性，如接口的位址，請求方式，參數及響應格式和錯誤資訊)

一緻性 (接口資訊一緻，不會出現因開發人員拿到的文檔版本不一緻，而出現分歧)

可測性 (直接在接口文檔上進行測試，以友善了解業務)

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

2.配置Swagger2

1.pom檔案中添加依賴

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

2.建立Swagger的配置檔案 SwaggerConfig.java

2.1.基本配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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 webApiConfig() {

        return new Docket(DocumentationType.SWAGGER_2);
    }

}
           

2.2.啟動服務檢視接口

端口号是自己測試的微服務端口号，swagger-ui.html是預設首頁面

http://localhost:6003/swagger-ui.html

swaggerUI顯示

3.分組配置及參數說明

3.1.Docket類

swagger配置類主要依賴于Docket類的實作，在Docket類中有關于分組設定的方法

3.2.配置基本的分組資訊

具體詳情配置如下圖，

①分組資訊groupName，swaggerUI顯示

②ApiInfo類，填寫swagger測試文檔描述資訊

導入的Contact包為springfox.documentation,service;不要導swagger的

Contact類有具體的聯系人描述資訊

swaggerUI顯示

③ApiSelectorBuilder類，選擇過濾哪些請求路徑

ApiSelectorBuilder中的方法

4.定義接口說明和參數說明

@Api：定義在類上

@ApiOperation：定義在方法上

@ApiParam：定義在參數上

swaggerUI顯示

5.定義entity實體類

5.1.注解，entity的實體類中可以添加一些自定義設定

@ApiModel：定義在entity實體類上

@ApiModelProperty：定義在實體類的屬性上

swaggerUI顯示

5.2.解決時間格式顯示錯誤

①在@ApiModelProperty中添加example格式樣例

②統一傳回的json時間格式

預設情況下json時間格式帶有時區，并且是世界标準時間，我們在東八區，時間差了八個小時

在application.yml中設定

spring:
  jackson: #傳回json的全局時間格式
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8
           

swaggerUI顯示