如何使用Swagger-UI線上生成漂亮的介面文件

Hanstrovsky發表於2020-04-18
SwaggerUI

一、簡單介紹

Swagger是一個實現了OpenAPI(OpenAPI Specification)規範的工具集。OpenAPI是Linux基金會的一個專案，試圖通過定義一種用來描述API格式或API定義的語言，來規範RESTful服務開發過程。

swagger大大方便了前後端開發人員，用過的人都說好。但是也有一些人並未體驗過swagger，還在苦苦的手寫介面文件，麻煩又不規範；還有一些人雖然用過，但是隻是朦朦朧朧，看別人怎麼用直接就CV過來用了，使用的很碎片，不繫統。我之前就是這個樣子，只知道新增個依賴，啟動專案後訪問：localhost:8080/swagger-ui.html，就能看到生成的文件了，很是簡單。

一次我看到生成的文件上總是多出來一個basic-error-controller，強迫症犯了，就想要把它弄掉，於是順便看了下swagger的配置，在這裡記錄一下。

官網：https://swagger.io/

看官方的說明：

Swagger包含的工具集：

  • Swagger編輯器： Swagger Editor允許您在瀏覽器中編輯YAML中的OpenAPI規範並實時預覽文件。
  • Swagger UI： Swagger UI是HTML，Javascript和CSS資產的集合，可以從符合OAS標準的API動態生成漂亮的文件。
  • Swagger Codegen：允許根據OpenAPI規範自動生成API客戶端庫（SDK生成），伺服器存根和文件。
  • Swagger Parser：用於解析來自Java的OpenAPI定義的獨立庫
  • Swagger Core：與Java相關的庫，用於建立，使用和使用OpenAPI定義
  • Swagger Inspector（免費）： API測試工具，可讓您驗證您的API並從現有API生成OpenAPI定義
  • SwaggerHub（免費和商業）： API設計和文件，為使用OpenAPI的團隊構建。

二、入門案例

SpringBoot已經整合了Swagger，使用簡單註解即可生成swagger的API文件。

1.引入依賴

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

2.編寫配置

@Configuration
@EnableSwagger2 // Swagger的開關，表示已經啟用Swagger
public class SwaggerConfig {
    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .host("localhost:8081")// 不配的話，預設當前專案埠
                .apiInfo(apiInfo())
                .pathMapping("/")
                .select() // 選擇哪些路徑和api會生成document
                .apis(RequestHandlerSelectors.any())// 對所有api進行監控
//                .apis(RequestHandlerSelectors.basePackage("com.hanstrovsky.controller"))// 選擇監控的package
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 只監控有ApiOperation註解的介面
                //不顯示錯誤的介面地址
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//錯誤路徑不監控
                .paths(PathSelectors.regex("/.*"))// 對根下所有路徑進行監控
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XXXX專案介面文件")
                .contact(new Contact("Hanstrovsky", "www.hanstrovsky.com", "Hanstrovsky@gmail.com"))
                .description("這是用Swagger動態生成的介面文件")
                .termsOfServiceUrl("NO terms of service")
                .license("The Apache License, Version 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0")
                .build();
    }
}

3.啟動測試

啟動服務，訪問：http://localhost:8081/swagger-ui.html

就能看到swagger-ui為我們提供的API頁面了：

可以看到我們編寫的介面，任意點選一個，即可看到介面的詳細資訊：

可以看到詳細的介面宣告，包括：

  • 請求方式：
  • 請求路徑
  • 請求引數
  • 響應等資訊

點選右上角的try it out!還可以測試介面。

三、常用註解

剛才的文件說明中，是swagge-ui根據介面自動生成，不夠詳細。如果有需要，可以通過註解自定義介面宣告。常用的註解包括：

/**
 @Api：修飾整個類，描述Controller的作用
 @ApiOperation：描述一個類的一個方法，或者說一個介面
 @ApiParam：單個引數描述
 @ApiModel：用物件來接收引數
 @ApiProperty：用物件接收引數時，描述物件的一個欄位
 @ApiResponse：HTTP響應其中1個描述
 @ApiResponses：HTTP響應整體描述
 @ApiIgnore：使用該註解忽略這個API
 @ApiError ：發生錯誤返回的資訊
 @ApiImplicitParam：一個請求引數
 @ApiImplicitParams：多個請求引數
 */

示例：

@PostMapping("/people")
@ApiOperation(value = "儲存人員資訊")
@ApiResponses({
       @ApiResponse(code = 0, message = "儲存成功"),
       @ApiResponse(code = 1, message = "儲存失敗")
})
public FrontResult save(
         @ApiParam(value = "儲存引數", example = "")
         @RequestBody People people) {
     people.setBirthday(Timestamp.valueOf(LocalDateTime.now()));
     return new FrontResult(FrontResult.SUCCEED, "儲存成功", peopleDao.save(people));
}

@Data
@ApiModel(description = "人員資訊儲存請求物件")
public class People {
    @ApiModelProperty(value = "人員編號")
    private Long id;
    @ApiModelProperty(value = "姓名", required = true,position = 1)
    private String name;
    @ApiModelProperty(value = "性別", required = true,position = 2)
    private String sex;
    @ApiModelProperty(value = "生日", required = true,position = 3)
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Timestamp birthday;
}

檢視文件：

四、美化一下

如果覺得用起來不太習慣，可以用Swagger-Bootstrap-UI 替換Swagger 預設的UI實現左右選單風格的Swagger-UI ，讓其看起來更清晰明瞭。

1.新增依賴

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/swagger-bootstrap-ui -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

2.重啟專案

訪問 http://localhost:8080/doc.html ：

相關文章