Spring Boot demo系列(七):Swagger

1 概述

Swagger主要用於生成API文檔,本文演示瞭如何使用目前最新的OpenAPI3以及Swagger來進行接口文檔的生成。html

2 依賴

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.7</version>
</dependency>

Gradlejava

implementation( "org.springdoc:springdoc-openapi-ui:1.4.7")

3 配置

Swagger的配置很簡單,僅須要一個@OpenAPIDefinition便可,@OpenAPIDefinition用於描述全局的配置信息,參考配置以下:git

  • info表示基本信息,好比標題,版本,描述等
  • externalDocs是參考文檔
  • servers是服務器地址
@OpenAPIDefinition(info = @Info(title = "標題",version = "版本",description = "描述"),
        externalDocs = @ExternalDocumentation(description = "參考文檔",url = "https://www.baidu.com"),
        servers = @Server(url = "http://localhost:8080"))
public class SwaggerConfig {
}

接着在配置文件寫上文檔路徑:github

springdoc:
  api-docs:
    path: /doc

4 訪問

運行後直接訪問spring

localhost:8080/swagger-ui/index.html/

會出現以下界面:api

在這裏插入圖片描述

搜索欄中輸入配置文件中的路徑/doc搜索便可:bash

在這裏插入圖片描述

或者直接訪問:服務器

http://localhost:8080/swagger-ui/index.html?url=/doc

5 控制器

下一步就是添加具體的接口,先來看一個簡單的例子:app

@RestController
@Tag(name = "測試Controller")
@RequestMapping("/")
public class TestController {
    @GetMapping("test")
    @Operation(description = "測試接口",tags = "測試Controller")
    public String test()
    {
        return "success";
    }
}

在這裏插入圖片描述

運行後能夠看到多了一個接口,也就是@Tag@Operation起做用了,註解說明以下:測試

  • @Tag表示標籤,name指定標籤的值,也能夠加上description等屬性
  • @Operation做用在方法上,能夠指定描述以及標籤,也能夠指定參數以及返回值等信息

相似的註解還有不少,好比:

  • @Parameter:指定參數屬性,好比descriptionname
  • @ApiResponse:指定返回值,經常使用的屬性有responseCode以及description
  • @Schema:用在實體類上以及實體類字段上,在接口上能夠顯示對應的值

6 完整示例

下面是一個接口控制器的完整示例:

@RestController
@Tag(name = "測試Controller")
@RequestMapping("/")
public class TestController {
    @GetMapping("test")
    @Operation(description = "測試接口",tags = {"測試Controller","測試"})
    public String test()
    {
        return "success";
    }

    @GetMapping("test2")
    @Operation(description = "這個也是測試接口",tags = {"測試Controller","2號測試接口"})
    @Parameter(description = "必要參數",name = "parm")
    public String test2(@RequestParam String parm)
    {
        return "須要參數";
    }

    @GetMapping("test3")
    @Operation(description = "帶有返回狀態的接口",tags = {"測試Controller"})
    @ApiResponse(responseCode = "111",description = "測試成功")
    @ApiResponse(responseCode = "222",description = "測試失敗")
    public void test3(@RequestBody String body)
    {
    }

    @GetMapping("test4")
    @Operation(description = "User接口",tags = {"測試Controller"})
    @ApiResponse(responseCode = "100",description = "添加成功")
    public void test4(@RequestBody User user)
    {
    }
}

實體類:

@Getter
@Schema(description = "用戶")
public class User {
    @Schema(description = "用戶名")
    private String name;
    @Schema(description = "主鍵")
    private String id;
}

效果如圖:

在這裏插入圖片描述

在這裏插入圖片描述

在這裏插入圖片描述

在這裏插入圖片描述

7 參考源碼

Java版:

Kotlin版:

相關文章
相關標籤/搜索