Swagger3 的配置和使用

Swagger 3 (OpenAPI 3) 简介

Swagger 3（或OpenAPI 3）是一个用于描述、设计和文档化RESTful Web服务的规范。它允许您以清晰、可理解的方式定义您的API，并提供工具来生成API文档、客户端SDK、服务器端存根等。

在Java Spring Boot应用中，我们通常使用SpringFox库来集成Swagger 3。

这里使用 springdoc-openapi

与swagger 2 不同的有注解的使用改变：

如下图：

1. 添加依赖

首先，您需要在项目的pom.xml（Maven）中添加openapi的依赖。例如，对于Maven：

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

 

2. 配置Swagger

在Spring Boot应用中，您通常可以通过Java配置类来配置Swagger。以下是一个简单的配置示例：

package com.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.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @Author 
 * @createTime 
 * @Version
 * @注释：
 */
@Configuration
public class Swagger3Config {

    // 此处为模块化配置，将API文档配置成几个模块，添加每个模块名，此次模块下所有API接口的统一前缀
   // 第一个模块
    @Bean
    public GroupedOpenApi PayApi()
    {
        return GroupedOpenApi.builder().group("教师文档API").pathsToMatch("/admin/edu/**").build();
    }



    // 第二个模块
    @Bean
    public GroupedOpenApi OssFileApi()
    {
        return GroupedOpenApi.builder().group("文件上传API").pathsToMatch("/admin/file/**").build();
    }


    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("swagger页面标题")
                        .description("描述")
                        .version("v1.0")
                        .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"));

    }
}

3.定义一个controller：

/**
 *
 * @author cb
 * 
 */
@RestController
@RequestMapping("/admin/edu/teacher")
@CrossOrigin
@Tag(name = "文档API",description = "查询信息")
public class  TeacherController {

    @Operation(description = "测试接口")
    @GetMapping("/getString")
    public String getTest(){
        return "swagger3 API接口测试成功";
    }


}

 4.3、启动项目，并打开swagger网址，利用Swagger Ui:

一旦配置了Swagger，您就可以使用Swagger UI来查看和测试您的API。默认情况下，Swagger UI的地址为：

http://localhost:自己的端口号/swagger-ui/index.html

总结

Swagger 3（OpenAPI 3）是一个强大的工具，用于描述、设计和文档化RESTful Web服务。通过集成SpringFox库，您可以轻松地在Spring Boot应用中使用Swagger。从添加依赖、配置Swagger到使用Swagger UI，这个过程相对简单且直观。