Springdoc替換swagger的實現(xiàn)步驟分解

更新時間：2023年02月15日 16:20:30 作者：碼農(nóng)-文若書生

最近在spring看到的，spring要對api文檔動手了，有些人說swagger不好用，其實也沒那么不好用，有人說代碼還是有點侵入性，這倒是真的，我剛試了springdoc可以說還是有侵入性但是也可以沒有侵入性，這就看你對文檔有什么要求了

前言

距離swagger上次發(fā)布版本已經(jīng)過去兩年多了，一直沒有更新，與當(dāng)前的springboot2.6.x、springboot2.7.x存在各種兼容問題，對于即將發(fā)布的springboot3.x，可能存在更多兼容問題。如下圖所示。

其實swagger還在更新，應(yīng)該是springfox不更新導(dǎo)致的，所以需要使用其他的API管理工具代替,springdoc是一種選擇

一、springdoc介紹

SpringDoc是一款可以結(jié)合SpringBoot使用的API文檔生成工具，基于OpenAPI 3，是一款更好用的Swagger庫！值得一提的是SpringDoc不僅支持Spring WebMvc項目，還可以支持Spring WebFlux項目，甚至Spring Rest和Spring Native項目。

二、使用步驟

1.引入庫

gradle：

api group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.11'

maven:

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

2.spring配置類

創(chuàng)建一個spring配置類，添加springdoc的配置

@AutoConfiguration
public class SpringDocConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("newframe-接口文檔")
                        .description("基于SpringDoc的在線接口文檔")
                        .version("0.0.1"));
    }
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("權(quán)限相關(guān)")
                .packagesToScan("com.iscas.biz.controller.common.auth")
                .build();
    }
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("默認(rèn)")
                .pathsToMatch("/**")
                .build();
    }
}

3.常用的swagger注解和springdoc的對應(yīng)關(guān)系

4.一個接口類的示例

@Tag(name = "組織機構(gòu)管理-OrgController")
@RestController
@RequestMapping("/org")
@Validated
@ConditionalOnMybatis
public class OrgController extends BaseController {
    private final OrgService orgService;

    public OrgController(OrgService orgService) {
        this.orgService = orgService;
    }
    @Operation(summary="[組織機構(gòu)]獲取組織機構(gòu)樹", description="create by:朱全文 2021-02-20")
    @GetMapping
    public TreeResponse get() throws BaseException {
        return getTreeResponse().setValue(orgService.getTree());
    }
    @Operation(summary="[組織機構(gòu)]新增組織機構(gòu)節(jié)點", description="create by:朱全文 2021-02-20")
    @io.swagger.v3.oas.annotations.parameters.RequestBody(required = true, description = "組織機構(gòu)數(shù)據(jù)",
            content = @Content(schema = @Schema(implementation = Org.class)))
    @PostMapping("/node")
    public ResponseEntity addNode(@Valid @RequestBody Org org) throws BaseException {
        return getResponse().setValue(orgService.addOrg(org));
    }
    @Operation(summary="[組織機構(gòu)]修改組織機構(gòu)節(jié)點", description="create by:朱全文 2021-02-20")
    @io.swagger.v3.oas.annotations.parameters.RequestBody(required = true, description = "組織機構(gòu)數(shù)據(jù)",
            content = @Content(schema = @Schema(implementation = Org.class)))
    @PutMapping("/node")
    public ResponseEntity editNode(@Valid @RequestBody Org org) {
        return getResponse().setValue(orgService.editOrg(org));
    }
    @Operation(summary="[組織機構(gòu)]刪除組織機構(gòu)節(jié)點", description="create by:朱全文 2021-02-20")
    @io.swagger.v3.oas.annotations.parameters.RequestBody(required = true, description = "組織機構(gòu)ID集合", content = @Content(examples = @ExampleObject(value = "[123, 124]")))
    @PostMapping("/node/del")
    @Caching(evict = {
            @CacheEvict(value = "auth", key = "'url_map'"),
            @CacheEvict(value = "auth", key = "'menus'"),
            @CacheEvict(value = "auth", key = "'role_map'")
    })
    public ResponseEntity deleteNode(@RequestBody List<Integer> orgIds) {
        AssertCollectionUtils.assertCollectionNotEmpty(orgIds, "orgIds不能未空");
        orgService.deleteNode(orgIds);
        return getResponse();
    }
}

5.配置文件配置

springdoc.swagger-ui.doc-expansion=none
springdoc.swagger-ui.path=/doc.html

還有其他的各種配置，可以在寫配置的時候查看提示

6.WebMvc配置

@AutoConfiguration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.
                addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                .resourceChain(false);
        registry.
                addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/swagger-ui/")
                .setViewName("forward:/swagger-ui/index.html");
    }
}