Swagger
主要用於生成API
文檔,本文演示瞭如何使用目前最新的OpenAPI3
以及Swagger
來進行接口文檔的生成。html
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.4.7</version> </dependency>
Gradle
:java
implementation( "org.springdoc:springdoc-openapi-ui:1.4.7")
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
運行後直接訪問spring
localhost:8080/swagger-ui/index.html/
會出現以下界面:api
搜索欄中輸入配置文件中的路徑/doc
搜索便可:bash
或者直接訪問:服務器
http://localhost:8080/swagger-ui/index.html?url=/doc
下一步就是添加具體的接口,先來看一個簡單的例子: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
:指定參數屬性,好比description
、name
等@ApiResponse
:指定返回值,經常使用的屬性有responseCode
以及description
@Schema
:用在實體類上以及實體類字段上,在接口上能夠顯示對應的值下面是一個接口控制器的完整示例:
@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; }
效果如圖:
Java
版:
Kotlin
版: