【SpringBoot】最新版3.x集成springdoc代替Swagger

ゝ一纸荒年。 2023-09-26 23:55 54阅读 0赞

## 背景 ##

`SpringBoot`升级为`3.x`后，包`javax`下的所有内容都迁移到了`jakarta`下，比如`HttpServletRequest`, 而`swagger`还是使用的包`javax`, 导致出现不兼容的问题，因此可以使用`springdoc`来替代以前的`swagger`

## 官网资料 ##

*  `https://springdoc.org/v2/index.html`

## 引入依赖pom.xml ##

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        </dependency>
    </dependencies>

## 示例Controller ##

@RestController
    public class DemoController {
        
    
        @Operation(summary = "示例",description = "示例描述")
        @RequestMapping(path = "/demo", method = RequestMethod.GET)
        public String demo(String name) {
        
            return "Hello," + name;
        }
    }

## 生成的文档效果 ##

\[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-N8vwkx2E-1682830067731)(./assets/【SpringBoot】最新版3.x集成springdoc代替Swagger-1682781287108.png)\]

## 配置类与配置文件 ##

以上是默认行为生成的效果，已经基本可以满足我们的需要，也可以通过配置类和配置文件定义更多特性

### 配置文件 ###

springdoc:
      packages-to-scan: ##需要扫描的包,可以配置多个
        - com.wen3.springdoc.demo.controller
      paths-to-exclude:  ##配置不包含在swagger文档中的api
        - /api/test/**
        - /api/mockito/data
      swagger-ui:
        enabled: true  #开启/禁止swagger,prod可以设置为false
        path: /swagger-ui.html  #swagger页面
      api-docs:
        enabled: true #开启/禁止api-docs, prod可以设置为false
        path: /api-docs #api的json文档
      use-management-port: false

### 配置类 ###

package com.wen3.springdoc.demo.autoconfigure;
    
    import io.swagger.v3.oas.models.ExternalDocumentation;
    import io.swagger.v3.oas.models.OpenAPI;
    import io.swagger.v3.oas.models.info.Contact;
    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;
    
    /**
     * @author tangheng
     */
    @Configuration
    public class SpringDocAutoConfiguration {
        
    
        @Bean
        public OpenAPI openAPI(){
        
            return new OpenAPI()
                    .info(apiInfo())
                    .externalDocs(new ExternalDocumentation()
                            .description("SpringDoc Wiki Documentation")
                            .url("https://springdoc.org/v2"));
        }
    
        private Info apiInfo() {
        
            return new Info()
                    .title("Wen3 Demo API Doc")
                    .description("springfox swagger 3.0 demo")
                    .version("1.0.0")
                    .contact(new Contact()
                            .name("demo")
                            .url("www.demo.com")
                            .email("demo@demo.com")
                    )
                    .license(new License()
                            .name("Apache 2.0")
                            .url("http://www.apache.org/licenses/LICENSE-2.0.txt")
                    );
        }
    }

## 常用的swagger注解和springdoc的对应关系 ##

<table> 
 <thead> 
  <tr> 
   <th align="left">SpringFox</th> 
   <th align="left">SpringDoc</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left">@Api</td> 
   <td align="left">@Tag</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiIgnore</td> 
   <td align="left">@Parameter(hidden = true)<br>@Operation(hidden = true)<br>@Hidden</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiImplicitParam</td> 
   <td align="left">@Parameter</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiImplicitParams</td> 
   <td align="left">@Parameters</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiModel</td> 
   <td align="left">@Schema</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiModelProperty</td> 
   <td align="left">@Schema</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiOperation(value=“示例”, notes=“示例描述”)</td> 
   <td align="left">@Operation(summary=“示例”,description=“示例描述”)</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiParam</td> 
   <td align="left">@Parameter</td> 
  </tr> 
  <tr> 
   <td align="left">@ApiResponse(code=404, message=“Not Found”)</td> 
   <td align="left">@ApiResponse(responseCode=“404”, description=“Not Found”)</td> 
  </tr> 
 </tbody> 
</table>