swagger3(openapi)

最新推荐文章于 2024-05-31 19:21:49 发布

少年纸鸢

最新推荐文章于 2024-05-31 19:21:49 发布

阅读量659

点赞数 5

文章标签： java

本文链接：https://blog.csdn.net/fengyifanjin/article/details/135850584

版权

本文介绍了如何在SpringDoc1.7.0和2.3.0版本中配置Swagger3.0(OpenAPI)，包括添加联系人信息、授权许可、文档描述，以及Swagger2.0到3.0注解的替换。还展示了如何使用`GroupedOpenApi`进行API分组和`application.yml`配置。

摘要由CSDN通过智能技术生成

之前写了一篇基于swagger2版本常用的注解(不太详细)，现在更新一版swagger3(openapi)版本的内容，用于后续使用查阅。

maven依赖

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

这里没直接用starter(很重)

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.3.0</version>
   </dependency>
springdoc-openapi-starter-webmvc-ui是一个 Maven Starter，
它包含了 springdoc-openapi-webmvc-core、springdoc-openapi-ui 
和 spring-boot-starter-web

package com.yifan_study.org.config;

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.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.HashMap;

@Configuration
public class SwaggerOpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {

        // 联系人信息(contact)，构建API的联系人信息，用于描述API开发者的联系信息，包括名称、URL、邮箱等
        // name：文档的发布者名称 url：文档发布者的网站地址，一般为企业网站 email：文档发布者的电子邮箱
        Contact contact = new Contact()
                .name("鞠七")                             // 作者名称
                .email("xxxxx@163.com")                   // 作者邮箱
                .url("https://blog.csdn.net/fengyifanjin?type=blog")  // 介绍作者的URL地址
                .extensions(new HashMap<String, Object>()); // 使用Map配置信息（如key为"name","email","url"）

        // 授权许可信息(license)，用于描述API的授权许可信息，包括名称、URL等；假设当前的授权信息为Apache 2.0的开源标准
        License license = new License()
                .name("Apache 2.0")                         // 授权名称
                .url("https://www.apache.org/licenses/LICENSE-2.0.html")    // 授权信息
                .identifier("Apache-2.0")                   // 标识授权许可
                .extensions(new HashMap<String, Object>());// 使用Map配置信息（如key为"name","url","identifier"）

        //创建Api帮助文档的描述信息、联系人信息(contact)、授权许可信息(license)
        Info info = new Info()
                .title("Swagger3.0 (Open API) 框架学习示例文档")      // Api接口文档标题（必填）
                .description("学习Swagger框架而用来定义测试的文档")     // Api接口文档描述
                .version("1.2.1")                                  // Api接口版本
                //.termsOfService("https://example.com/")            // Api接口的服务条款地址
                .license(license)                                  // 设置联系人信息
                .contact(contact);                                 // 授权许可信息
        // 返回信息
        return new OpenAPI()
                .openapi("3.0.1")  // Open API 3.0.1(默认)
                .info(info);       // 配置Swagger3.0描述信息
    }


    @Bean
    public GroupedOpenApi yiFanStudyOrgApi() {
        return GroupedOpenApi.builder()
                .group("yifan_studyOrg")
                .packagesToScan("com.yifan_study.org")
                .build();
    }

    @Bean
    public GroupedOpenApi yiFanStudyDemoApi() {
        return GroupedOpenApi.builder()
                .group("yifan_studyDemo")
                .packagesToScan("com.yifan_study.demo")
                .build();
    }
}

上面这两个GroupedOpenApi 是进行分组用的不分组可以写一个(下图解释)
在这里插入图片描述

上面是配置改动
下面是application.yml

springdoc:
  api-docs:
    path: /springdoc  #ip+端口/springdoc  访问swagger文档
    enabled: true
  swagger-ui:
    path:  /swagger-ui.html  #ip+端口/swagger-ui.html 访问swagger页面
    enabled: true

swagger2—》swagger3(openapi) 注解替换

@Api→@Tag

@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@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")