Springdoc使用Swagger3、OpenApi规范

Springdoc使用
这里只是粗略展示了一下用法，具体还得看Swagger3和Springdoc的官方文档
Swagger3配置官方文档
springdoc官方文档
导入依赖

		 <dependency>
		      <groupId>org.springframework.boot</groupId>
		      <artifactId>spring-boot-starter-actuator</artifactId>
		  </dependency>
        <!--开启springdoc支持webmvc-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-webmvc-core</artifactId>
            <version>1.6.6</version>
        </dependency>
        <!--开启openapi-ui-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.6</version>
        </dependency>

application.yaml配置

spring:
  application:
    name: springfox-swagger

server:
  port: 8080

# springdoc设置 官方文档: https://springdoc.org/#modules
# springdoc当前版本全部基于swagger3，所以
# swagger3的api规范在springdoc里面都可以用 https://swagger.io/specification/
# swagger属性规范 https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
# 一定要对照上面3个官方文档
springdoc:

  # 展示到actuator中
  show-actuator: true
  # 使用管理端口
  use-management-port: true
  #扫描的包列表 默认: *
  packages-to-scan: com.hhoa
  # 匹配的路径列表 默认: /*
  #  paths-to-match: /*
  # 匹配的标题列表 默认: /*
  # headers-to-match:
  # 匹配的消耗媒体类型
  # consumes-to-match:
  # 排除的路径列表
  # paths-to-exclude:
  # 排除的包列表
  # packages-to-exclude:

  # 设置api-docs
  api-docs:
    # 设置api-docs路径 默认: /v3/api-docs 如果开启了管理端口，那么这个也就失效了直接用/actuator/group-name代替
    path: /api-docs
    # 是否启用 默认: true
    enabled: true

  # swagger-ui配置 支持所有官方属性https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
  swagger-ui:
    # 设置可以直接从应用根路径访问swagger-ui
    # use-root-path: true
# actuator管理
management:
  endpoints:
    web:
      # 暴露端口
      exposure:
        include: openapi, swaggerui
  # 设置管理端口
  server:
    port: 9090

SwaggerConfig配置

package com.hhoa.config;

import com.hhoa.bean.User;
import io.swagger.v3.oas.models.*;
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 io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.media.MediaType;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.parameters.RequestBody;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.servers.Server;
import io.swagger.v3.oas.models.servers.ServerVariable;
import io.swagger.v3.oas.models.servers.ServerVariables;
import io.swagger.v3.oas.models.tags.Tag;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;


/**
 * @author hhoa
 */
@Configuration
public class SwaggerConfig {
    /**
     * 您可以根据以下组合定义自己的 API 组：API 路径和要扫描的包。
     * 每个组都应该有一个独特的 groupName.
     * 该组的 OpenAPI 描述，默认情况下可用于：
     * http://server:port/context-path/v3/api-docs/groupName
     * 开启了
     * http://server:port/actoator/openapi/groupName
     * @return GroupedOpenApi
     */
    @Bean
    public GroupedOpenApi publicApi(){
        return GroupedOpenApi.builder()
                .group("user")
                .packagesToScan("com.hhoa.controller.UserController")
                .build();

    }
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .pathsToMatch("/**")
                .build();
    }


    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                //必须
                .info(new Info()
                        //必须
                        .title("标题")
                        .description("描述")
                        //必须, 版本
                        .version("版本")
                        .license(new License()
                                        //如果定义了license就是必须
                                        .name("license名字")
                                .url("license的url"))
                        .contact(new Contact()
                                        .name("联系者的名字")
                                        .url("联系者的url")
                                        .email("联系人的email")))
                .servers(List.of(new Server()
                                //必须
                                .url("服务器网址")
                                .description("描述")
                                .variables(new ServerVariables()
                                        .addServerVariable("变量名称", new ServerVariable()
                                                ._enum(List.of("枚举"))
                                                //必须
                                                ._default("参数值")
                                                .description("描述")))))
                //必须,这个一般在controller里面生成，不在这里定义
                .paths(new Paths()
                        .addPathItem("路径名", new PathItem()
                                .$ref("参考")
                                .summary("概括")
                                .description("描述")
                                //操作类型，还有post, put, delete
                                .get(new Operation()
                                        .tags(List.of("标签1", "标签2"))
                                        .summary("概括")
                                        .description("描述")
                                        .externalDocs(new ExternalDocumentation()
                                                .description("描述")
                                                //必须
                                                .url("url"))
                                        .operationId("操作标识")
                                        .parameters(List.of(new Parameter()
                                                .name("名字")
                                                //必须的, 可能在"query", "header", "path", "cookie"中
                                                .in("参数的位置")
                                                .description("描述")
                                                .required(false)
                                                .deprecated(false)
                                                .allowEmptyValue(true)))
                                        .requestBody(new RequestBody()
                                                .$ref("引用")
                                                .description("描述")
                                                //必须
                                                .content(new Content()
                                                        .addMediaType("Media名字",new MediaType()
                                                                .schema(new Schema<User>()
                                                                        /*
                                                                        JSON Schema规范，属性太多了，不想写了，自己看吧:
                                                                            与OpenApi遵循相同规范:
                                                                                title,multipleOf,maximum,exclusiveMaximum,minimum,
                                                                                exclusiveMinimum,maxLength,minLength,pattern,maxItems,
                                                                                minItems,uniqueItems,maxProperties,minProperties,required,enum
                                                                            根据OpenApi进行了调整:
                                                                                type, allOf, oneOf, anyOf, not, items, properties,
                                                                                additionalProperties, description,format, default
                                                                            ref
                                                                            扩展字段:
                                                                                nullable, discriminator, readOnly,
                                                                                writeOnly, xml, externalDocs, example
                                                                                deprecated
                                                                         */
                                                                        )
                                                                .example("任何对象")))
                                                .required(true)))))
                .components(new Components())
                .servers(List.of(new Server()))
                .security(List.of(new SecurityRequirement()))
                .tags(List.of(new Tag()))
                .externalDocs(new ExternalDocumentation()
                        .description("swagger官方文档")
                        .url("https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/"));

    }
}