作者 | 咖啡伴侶

76套java從入門到精通實戰課程分享

SpringDoc基於swagger，並做了更多的對Spring系列各框架的相容，用法上與Swagger3基本相同，並多了一些自己的配置，相較於Swagger3來說，更好用，支援也更好一點

開發環境

. JDK1.8. SpringBoot 2.4.2

新增Maven依賴新增配置類

package cn.lixuelong.hs;import io.swagger.v3.oas.models.ExternalDocumentation;import io.swagger.v3.oas.models.OpenAPI;import io.swagger.v3.oas.models.info.Info;import io.swagger.v3.oas.models.info.License;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;@Configurationpublic class OpenApiConfig { @Bean public OpenAPI springShopOpenAPI() { return new OpenAPI() .info(new Info().title("SpringShop API") .description("Spring shop sample application") .version("v0.0.1") .license(new License().name("Apache 2.0").url("http://springdoc.org"))) .externalDocs(new ExternalDocumentation() .description("SpringShop Wiki Documentation") .url("https://springshop.wiki.github.org/docs")); }}

新增properties配置

#指定介面包掃描springdoc.packagesToScan=cn.lixuelong.hs.api#或者指定訪問介面路徑掃描#springdoc.pathsToMatch=/hs/**, /hsType/**

使用SpringDocController上新增 @Tag 註解介面方法上新增 @Operation 註解對介面引數新增 @Parameters 和 @Parameter 註解

示例如下：

package cn.lixuelong.hs.api;import cn.lixuelong.hs.domain.Hs;import cn.lixuelong.hs.domain.HsType;import cn.lixuelong.hs.service.HsService;import cn.lixuelong.hs.service.HsTypeService;import com.alibaba.fastjson.JSONObject;import io.swagger.v3.oas.annotations.Operation;import io.swagger.v3.oas.annotations.Parameter;import io.swagger.v3.oas.annotations.Parameters;import io.swagger.v3.oas.annotations.tags.Tag;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PutMapping;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RestController;import javax.annotation.Resource;import java.util.Date;@Tag(name = "操作介面", description = "操作描述")@RestController@RequestMapping("hs")public class HsApi { @Resource private HsService hsService; @Resource private HsTypeService hsTypeService; @Operation(summary = "新增", description = "新增描述") @Parameters({ @Parameter(name = "name", description = "名字", required = true), @Parameter(name = "typeId", description = "型別ID", required = true) }) @PutMapping("add") public JSONObject add(String name, Long typeId) { HsType hsType = hsTypeService.findById(typeId); Hs hs = new Hs(); hs.setName(name); hs.setType(hsType); hs.setDateCreated(new Date()); hs = hsService.save(hs); return JSONObject.parseObject(JSONObject.toJSONString(hs)); } @Operation(summary = "獲取") @GetMapping("get") public JSONObject get(@Parameter(name = "id", description = "資料ID") Long id) { Hs hs = hsService.findById(id); return JSONObject.parseObject(JSONObject.toJSONString(hs)); }}

成果展示

啟動服務後，就可以檢視線上文件了，本地服務的地址是[http://localhost:8080/swagger-ui.html]http://localhost:8080/swagger-ui.html，還可以透過Try it out 來測試

訪問http://localhost:8080/v3/api-docs可以檢視線上文件的JSON格式資料

其它配置

. 修改線上文件的訪問路徑

# /api-docs endpoint custom pathspringdoc.api-docs.path=/api-docs

. 關閉線上文件JSON格式資料（關閉後會影響SwaggerUI頁）

# Disabling the /v3/api-docs enpointspringdoc.api-docs.enabled=false

. 關閉線上文件SwaggerUI

# Disabling the swagger-uispringdoc.swagger-ui.enabled=false

SpringDoc與Swagger2的註解的對應關係