Swagger的介绍与使用（二）

一. 介绍( Spring Boot + JDK 17 + Swagger 3（OpenAPI）结合使用)

根据2024年当前环境来看， Spring Boot + JDK 17 + Swagger 3（OpenAPI）结合使用更加有趋势

将Spring Boot、JDK 17和Swagger 3（OpenAPI）结合使用，可以带来以下好处：

快速开发：Spring Boot的自动配置和简化部署特性，结合JDK 17的新特性和改进，可以极大地提高开发效率。
API文档自动化：Swagger 3（OpenAPI）能够自动生成API文档，并提供可视化界面，使得API的调用和测试变得更加简单和直观。
跨平台支持：Java的跨平台特性，结合Spring Boot的轻量级和独立运行能力，使得开发的应用可以轻松部署到各种环境中。
标准化和可维护性：OpenAPI规范为RESTful API提供了一种标准化的描述方式，有助于提高API的可维护性和可扩展性。

二. 使用

1> 添加Maven依赖

<!-- openAPI包，替换 Swagger 的 SpringFox -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>

2> 添加application.yml配置文件

与application.properties相同，更加简洁

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

3> 添加OpenAPIConfig，配置Swagger

package com.nianxi.srping_demo.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenAPIConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("接口文档标题")
                        .description("SpringBoot3 集成 Swagger3接口文档")
                        .version("v1"))
                .externalDocs(new ExternalDocumentation()
                        .description("项目API文档")
                        .url("/"));
    }
}

4> 添加SwaggerController

package com.nianxi.srping_demo.controller;

import com.nianxi.srping_demo.model.SwaggerApiModel;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
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 org.springframework.web.bind.annotation.*;

@Tag(name = "控制器：测试Swagger3", description = "描述：测试Swagger3")
@RestController
public class SwaggerController {

    @Operation(summary = "测试Swagger3注解方法Get")
    @Parameters({@Parameter(name = "id",description = "编码"),
            @Parameter(name = "headerValue",description = "header传送内容")})
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "请求成功"),
            @ApiResponse(responseCode = "400", description = "请求参数没填好"),
            @ApiResponse(responseCode = "401", description = "没有权限"),
            @ApiResponse(responseCode = "403", description = "禁止访问"),
            @ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")
    })
    @GetMapping(value = "/swagger/student")
    public Object getStudent(@RequestParam @Parameter(example = "2")  String id,
                             @RequestHeader @Parameter(example = "2") String headerValue){
        return id;
    }

    @Operation(summary = "测试Swagger3注解方法Post")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "请求成功"),
            @ApiResponse(responseCode = "400", description = "请求参数没填好"),
            @ApiResponse(responseCode = "401", description = "没有权限"),
            @ApiResponse(responseCode = "403", description = "禁止访问"),
            @ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")
    })
    @PostMapping(value = "/swagger/student", produces = "application/json")
    public SwaggerApiModel updateStudent(@RequestBody SwaggerApiModel model){
        return model;
    }


    /**
     * swagger 不暴漏该 api，通过@Hidden隐藏
     * 但是仍然可以访问
     * @return
     */
    @Hidden
    @GetMapping(value = "/swagger/hiddenApi")
    public String hiddenApi(){
        return "hiddenApi";
    }

    /**
     * swagger 暴漏该 api，没有配置@Hidden会展示
     * @return
     */
    @GetMapping(value = "/swagger/noHiddenApi")
    public String noHiddenApi(){
        return "noHiddenApi";
    }
}

5> 添加SwaggerModel实体

package com.nianxi.srping_demo.model;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

import java.io.Serializable;

@Data
@Schema(description= "学生信息")
public class SwaggerApiModel implements Serializable {

    @Schema(description = "主键ID", required = true, example = "1")
    private Long id;//required表示是否必填

    @Schema(description = "手机号", required = true)
    private String phonenum;

    @Schema(description = "密码", required = true)
    private String password;

    @Schema(description = "年龄", required = true)
    private Integer age;

}

5> 启动Application启动类进行测试

输入local:8080/swagger-ui/index.html

如果打开失败可以查看自己idea日志

端口号要一致

三. 注解分析

1. 基本信息注解

@OpenAPIDefinition

描述：用于定义整个 API 文档的基本信息。
可用于：类、接口。
属性：
- info：指定 @Info 注解的对象，用于描述 API 文档的基本信息。

@Info

描述：用于定义 API 文档的基本信息。
可用于：类、接口。
属性：
- title：API 的标题。
- description：API 的描述。
- version：API 的版本号。
- termsOfService：服务条款的 URL。
- contact：指定 @Contact 注解的对象，用于描述联系人信息。
- license：指定 @License 注解的对象，用于描述许可证信息。

@Contact

描述：用于定义 API 文档中的联系人信息。
可用于：类、接口。
属性：
- name：联系人的名称。
- url：联系人的网址。
- email：联系人的电子邮件地址。

@License

描述：用于定义 API 文档中的许可证信息。
可用于：类、接口。
属性：
- name：许可证的名称。
- url：许可证的网址。

2. 分组注解

@Tag

描述：用于给 API 分组，用途类似于为 API 文档添加标签。
可用于：方法、类、接口。
属性：
- name：分组的名称。

3. 请求方法注解

以下注解用于描述 API 的请求方法：

@Operation

描述：用于描述 API 的操作。
可用于：方法。
属性：
- summary：操作的摘要信息。
- description：操作的详细描述。
- tags：指定 @Tag 注解的对象数组，用于将操作归类到特定的分组。
- parameters：指定 @Parameter 注解的对象数组，用于描述操作的输入参数。
- responses：指定 @ApiResponse 注解的对象数组，用于描述操作的响应结果。
- requestBody：指定 @RequestBody 注解的对象，用于描述操作的请求体。

@Parameter

描述：用于描述操作的输入参数。
可用于：方法。
属性：
- name：参数的名称。
- in：参数的位置，可以是 path、query、header、cookie 中的一种。
- description：参数的描述。
- required：参数是否必需，默认为 false。
schema：指定 @Schema 注解的对象，用于描述参数的数据类型。