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/"));
}
}
类似资料：