如题，我这是在Springboot3中集成swagger用于生成文档，但目前好像swagger只支持到Springboot2，我是怎么做到Springboot3集成swagger的呢？
很显然，我集成的不是swagger，而是springdoc
老规矩，先放官网：springdoc.org/
一：添加POM依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>
二：YML配置
# ===== SpringDoc配置 =====#
springdoc:
swagger-ui:
enabled: false
# 自定义的文档界面访问路径。默认访问路径是/swagger-ui.html
path: /swagger-ui.html
# 字符串类型，一共三个值来控制操作和标记的默认展开设置。它可以是“list”（仅展开标记）、“full”（展开标记和操作）或“none”（不展开任何内容）。
docExpansion: none
# 布尔值。控制“试用”请求的请求持续时间（毫秒）的显示。
displayRequestDuration: true
# 布尔值。控制供应商扩展（x-）字段和操作、参数和架构值的显示。
showExtensions: true
# 布尔值。控制参数的扩展名（pattern、maxLength、minLength、maximum、minminimum）字段和值的显示。
showCommonExtensions: true
# 布尔值。禁用swagger用户界面默认petstore url。（从v1.4.1开始提供）。
disable-swagger-default-url: true
api-docs:
# enabled the /v3/api-docs endpoint
enabled: false
# 自定义的文档api元数据访问路径。默认访问路径是/v3/api-docs
path: /springdoc/api-docs
# 布尔值。在@Schema（名称name、标题title和说明description，三个属性）上启用属性解析程序。
resolve-schema-properties: true
# 布尔值。实现OpenApi规范的打印。
writer-with-default-pretty-printer: true
# 配置扫描接口包
#packages-to-scan: con.modules #
三：config配置类
package com.modules.swagger.config;
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;
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI openAPI()
{
return new OpenAPI()
.info(new Info()
.title("测试 title")
.description("SpringBoot3 集成 Swagger3")
.version("v1"))
.externalDocs(new ExternalDocumentation()
.description("项目API文档")
.url("/"));
}
}
到这里，springboot3集成springdoc就已经完成了。
四：配置springdoc只能在开发环境中访问
创建三个yml配置文件，如上图所示。
这个我就不过多解释了，application.yml为主配置文件，application-dev.yml为开发环境配置文件，application-pro.yml为生产环境配置文件。
application.yml文件内容上方已展示，这里不再赘述
application-dev.yml内容如下：
springdoc:
api-docs:
enabled: true
swagger-ui:
enabled: true
application-pro.yml内容如下：
springdoc:
api-docs:
enabled: false
swagger-ui:
enabled: false
上线打包的时候使用application-pro.yml配置文件即可。
五：springdoc常用注解
默认是可以不配置任何注解的，不过增加一些注解可以使swagger可读性更加好。
| 注解SpringBoot3 版本 | 替换旧注解 SpringBoot2 版本 | 描述 |
|---|---|---|
| @Tag | @Api | 用于标注一个Controller（Class）。 在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。 |
| @Operation | @ApiOperation | 用于对一个操作或HTTP方法进行描述。 具有相同路径的不同操作会被归组为同一个操作对象。 不同的HTTP请求方法及路径组合构成一个唯一操作。 |
| @Parameter | @ApiParam | @Parameter作用于请求方法上，定义api参数的注解。 |
| @Parameters、 @Parameter | @ApiImplicitParams、@ApiImplicitParam | 都可以定义参数 （1）@Parameters：用在请求的方法上，包含一组参数说明 （2）@Parameter：对单个参数的说明 |
| io.swagger.v3.oas.annotations新包中的@ApiResponses、@ApiResponse | 旧包io.swagger.annotations中的@ApiResponses、@ApiResponse | 进行方法返回对象的说明。 |
| @Schema | @ApiModel、@ApiModelProperty | @Schema用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景）。 |
注解使用代码示例：
package com.modules.article.controller;
import com.modules.article.service.ArticleService;
import com.modules.customannotations.myAnnotation.MySentinelResource;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.constraints.NotEmpty;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.util.Map;
/**
* 文章部分接口
* @className AboutController
* @author camellia
* @email 805795955@qq.com
* @date 2023/01/01
* @version 1.0
*/
@RequestMapping("java")
@RestController
@Validated
@Tag(name = "测试Swagger3", description = "测试Swagger3注解")
//@CrossOrigin(origins="*",maxAge=3600)
public class ArticleController
{
// 自动装载（dao接口注入）
@Autowired
private ArticleService articleService;
/**
* 测试邮件发送
* @return
* @throws Exception
*/
@Operation(summary = "测试Swagger3注解方法Get")
@GetMapping("article/testMail")
@MySentinelResource(resource = "getData", number = 1) // 自定义注解：sentinel限流
public Map<String, Object> testMail() throws Exception
{
articleService.updateArticleTime();
//email.sendSimpleMail("805795955@qq.com","测试邮件","成功了嘛？");
System.out.println("testmail");
return null;
}
/**
* 文章详情
* @param article_id
* @param request
* @return
* @throws Exception
*/
@Operation(summary = "测试Swagger3注解方法getArticleDetail")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "请求成功"),
@ApiResponse(responseCode = "400", description = "请求参数没填好"),
@ApiResponse(responseCode = "401", description = "没有权限"),
@ApiResponse(responseCode = "403", description = "禁止访问"),
@ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")
})
@GetMapping("article/getArticleDetail")
@MySentinelResource(resource = "getData", number = 1) // 自定义注解：sentinel限流
public Map<String, Object> getArticleDetail(@NotEmpty(message = "id不能为空") @RequestParam(defaultValue = "") String article_id, HttpServletRequest request) throws Exception
{
Map<String, Object> result = articleService.getArticleDetail(article_id,request);
return result;
}
/**
* 提交评论
* @param article_id 文章id
* @param email 邮箱
* @param content 评论内容
* @param content_reply 回复内容
* @param replyid 回复评论id
* @param request 请求对象
* @Response code 操作状态
* @Response msg 返回语
* @throws Exception
*/
@GetMapping("article/putComment")
public Map<String, Object> putComment(@RequestParam(defaultValue = "") String article_id, @RequestParam(defaultValue = "") String email, @RequestParam(defaultValue = "") String content, @RequestParam(defaultValue = "") String content_reply,@RequestParam(defaultValue = "") String replyid,HttpServletRequest request) throws Exception
{
Map<String, Object> result = articleService.putComment(article_id,email,content,content_reply,replyid,request);
return result;
}
}
新增SwaggerApiModel.java，测试@Schema注解
package com.modules.article.controller;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.io.Serializable;
@Data
@Schema(description= "用户信息")
public class User implements Serializable {
@Schema(description = "id", required = true)
private Long id;
@Schema(description = "姓名", required = true)
private String name;
@Schema(description = "年龄", required = true)
private Integer age;
@Schema(description = "性别", required = true)
private Integer sex;
}
这个时候浏览器访问：http://localhost:8001/swagger-ui.html
界面显示：
我们上方的配置落实在界面上就是这个样子的。完美~
六：使用Springdoc的API请求功能测试接口
这就很方便我们开发调试了，要不然还得专门下载一个api请求工具做请求。
这个很简单，我就不做过多的赘述了。放一张我使用的时候的截图叭。
以上就是咱们常用的 SpringBoot3 版本项目集成Swagger3的方法，可以说不复杂，按照我上面的配置即可实现。
有好的建议，请在下方输入你的评论。
