升级到springdoc的Swagger3

本文介绍了如何在SpringBoot3.0应用中从Swagger2迁移到Swagger3,包括依赖更新、注解变化以及创建配置类以设置API文档。详细列出了不同注解的迁移路径和示例代码。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

jdk 17、springboot3

依赖配置:就此一个依赖即可

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.5.0</version>
   </dependency>

Swagger2->Swagger3注解

  • @Api → @Tag

  • @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden

  • @ApiImplicitParam → @Parameter

  • @ApiImplicitParams → @Parameters

  • @ApiModel → @Schema

  • @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)

  • @ApiModelProperty → @Schema

  • @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")

  • @ApiParam → @Parameter

  • @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

添加Swagger配置类


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 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"));
  }



}

### 如何配置 Swagger 3 API 接口文档 #### 使用 Spring Boot 和 SpringFox 实现 Swagger 3 配置 为了实现更现代的 API 文档生成功能,可以考虑升级至 OpenAPI 3.x 版本。Springfox 是一个用于生成 RESTful APIs 的工具集,在最新版本中支持了 OpenAPI 3。 对于基于 Spring Boot 的项目来说,可以通过引入 `springdoc-openapi-ui` 来轻松集成并启用 Swagger UI 功能: ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.14</version><!-- 确认使用稳定版 --> </dependency> ``` 此依赖项将会自动扫描应用程序中的所有控制器,并根据其注解来自动生成对应的 API 描述文件[^1]。 #### Flask 应用程序下的 Swagger 3 设置方法 如果是在 Python 生态圈内工作,则可能倾向于采用类似于Flask这样的Web框架来构建服务端应用。此时推荐利用 `flasgger` 这一库来进行Swagger/OpenAPI规范的支持: 安装命令如下所示: ```bash pip install flasgger ``` 接着可以在代码里定义好相应的元数据以及路径规则之后加载 Flasgger 扩展模块即可完成基本设置[^2]: ```python from flask import Flask, jsonify from flasgger import Swagger app = Flask(__name__) template = { "swagger": "3.0", "info": { "title": "My App Documentation", "description": "This is a sample app demonstrating how to integrate swagger with flask.", "contact": { "responsibleOrganization": "ME", "email": "me@example.com" }, "termsOfService": "http://me.example.com/terms", "version": "1.0" } } swag = Swagger(app, template=template) @app.route(&#39;/example&#39;) def example(): """ Example endpoint returning some data. --- get: description: Returns an example response containing JSON object. responses: &#39;200&#39;: content: application/json: schema: type: object properties: message: type: string example: Hello world! """ return jsonify({"message":"Hello world!"}) ``` 上述例子展示了如何通过YAML格式编写OpenAPI v3风格的操作描述,并将其嵌入到视图函数上方作为多行字符串的一部分。这使得开发者能够更加直观地控制每一个HTTP请求的行为及其预期返回值结构。
评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值