Site oficial do springdoc-openapi: springdoc.org
springdoc-openapi Github: springdoc / springdoc-openapi
springdoc-openapi Maven: Home » org.springdoc » springdoc-openapi-ui
introdução da API aberta
OpenApi é um padrão e uma especificação de documento de API do setor.
Por exemplo, um conceito abstrato em Java é uma classe abstrata, que fornece apenas um método abstrato padronizado em um documento API.
Este método é atualmente implementado por duas implementações não oficiais principais, uma é springfox e a outra é springdoc.
introdução arrogante
Swagger é uma organização de manutenção de documentos API e mais tarde se tornou o principal definidor do padrão Open API. A versão mais recente é Swagger3 (Open Api3) lançada em 2017.
Introdução ao springdoc
SpringDoc também é um projeto (não oficial) mantido pela comunidade spring para ajudar os usuários a integrar o swagger3 ao Spring. Ele também é usado para ajudar os desenvolvedores a gerar documentação no Spring e pode ser facilmente usado na inicialização do Spring.
Os projetos desta organização suportam login Oauth2 da página swagger (conteúdo da Open API3), comparado ao Springfox, tem um tempo de suporte mais longo e é, sem dúvida, uma escolha melhor.
springdoc-openapi funciona inspecionando o aplicativo em tempo de execução, inferindo a semântica da API com base na configuração do Spring, estrutura de classes e várias anotações. Gere documentação automaticamente em APIs de formato JSON/YAML e HTML. Esta documentação pode ser realizada usando anotações da API Swagger.
A biblioteca springdoc-openapi suporta:
- OpenAPI3
- Spring-boot (v1 e v2)
- JSR-303, especificamente para @NotNull, @Min, @Max e @Size. Swagger-ui
- OAuth2
Uso integrado
Introduza springdoc-openapi-uidependências no projeto Maven:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.4.3</version>
</dependency>
Relacionamento de mapeamento de anotação Springfox e springdoc:
@Api -> @Tag
@ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @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")
Referência do arquivo de configuração application.yml:
spring:
application:
name: springdoc-openapi
server:
port: 8080
# ===== SpringDoc配置 =====#
springdoc:
swagger-ui:
# 自定义的文档界面访问路径。默认访问路径是/swagger-ui.html
path: /springdoc/docs.html
# 字符串类型，一共三个值来控制操作和标记的默认展开设置。它可以是“list”（仅展开标记）、“full”（展开标记和操作）或“none”（不展开任何内容）。
docExpansion: none
# 布尔值。控制“试用”请求的请求持续时间（毫秒）的显示。
displayRequestDuration: true
# 布尔值。控制供应商扩展（x-）字段和操作、参数和架构值的显示。
showExtensions: true
# 布尔值。控制参数的扩展名（pattern、maxLength、minLength、maximum、minminimum）字段和值的显示。
showCommonExtensions: true
# 布尔值。禁用swagger用户界面默认petstore url。（从v1.4.1开始提供）。
disable-swagger-default-url: true
api-docs:
# enabled the /v3/api-docs endpoint
enabled: true
# 自定义的文档api元数据访问路径。默认访问路径是/v3/api-docs
path: /springdoc/api-docs
# 布尔值。在@Schema（名称name、标题title和说明description，三个属性）上启用属性解析程序。
resolve-schema-properties: true
# 布尔值。实现OpenApi规范的打印。
writer-with-default-pretty-printer: true
# ===== swagger配置 =====#
swagger:
application-name: ${spring.application.name}
application-version: 1.0
application-description: springdoc openapi整合Demo
try-host: http://localhost:${server.port}
classe de configuração swagger:
@Component
@ConfigurationProperties("swagger")
public class SwaggerProperties {
/**
* 项目应用名
*/
private String applicationName;
/**
* 项目版本信息
*/
private String applicationVersion;
/**
* 项目描述信息
*/
private String applicationDescription;
/**
* 接口调试地址
*/
private String tryHost;
public String getApplicationName() {
return applicationName;
}
public void setApplicationName(String applicationName) {
this.applicationName = applicationName;
}
public String getApplicationVersion() {
return applicationVersion;
}
public void setApplicationVersion(String applicationVersion) {
this.applicationVersion = applicationVersion;
}
public String getApplicationDescription() {
return applicationDescription;
}
public void setApplicationDescription(String applicationDescription) {
this.applicationDescription = applicationDescription;
}
public String getTryHost() {
return tryHost;
}
public void setTryHost(String tryHost) {
this.tryHost = tryHost;
}
}
Um exemplo completo e detalhado de configuração do springdoc openapi:
import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.headers.Header;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.servers.Server;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springframework.boot.SpringBootVersion;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import java.lang.reflect.Field;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@Configuration
public class SpringdocOpenapiConfiguration implements WebMvcConfigurer {
private final SwaggerProperties swaggerProperties;
public SpringdocOpenapiConfiguration(SwaggerProperties swaggerProperties) {
this.swaggerProperties = swaggerProperties;
}
@Bean
public OpenAPI springDocOpenAPI() {
//配置认证、请求头参数
Components components = new Components();
Map<String, Object> myHeader2extensions = new HashMap<>(2);
myHeader2extensions.put("name", "myHeader2");
components
.addSecuritySchemes("bearer-key", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))
.addSecuritySchemes("basicScheme", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("basic"))
.addParameters("myHeader1", new Parameter().in("header").schema(new StringSchema()).name("myHeader1"))
//注：这种方式有问题，不推荐
.addHeaders("myHeader2", new Header().description("myHeader2 header").schema(new StringSchema()).extensions(myHeader2extensions))
.addParameters("myGlobalHeader", new HeaderParameter().required(true).name("My-Global-Header").description("My Global Header").schema(new StringSchema()).required(false))
;
// 接口调试路径
Server tryServer = new Server();
tryServer.setUrl(swaggerProperties.getTryHost());
return new OpenAPI()
.components(components)
.servers(Collections.singletonList(tryServer))
.info(new Info()
.title(swaggerProperties.getApplicationName() + " Api Doc")
.description(swaggerProperties.getApplicationDescription())
.version("Application Version: " + swaggerProperties.getApplicationVersion() + "\n Spring Boot Version: " + SpringBootVersion.getVersion())
.license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))
)
.externalDocs(new ExternalDocumentation()
.description("SpringDoc Full Documentation")
.url("https://springdoc.org/")
);
}
/**
* 添加全局的请求头参数
*/
@Bean
public OpenApiCustomiser customerGlobalHeaderOpenApiCustomiser() {
return openApi -> openApi.getPaths().values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
.forEach(operation -> {
operation.addParametersItem(new HeaderParameter().$ref("#/components/parameters/myGlobalHeader"));
});
}
/**
* 通用拦截器排除设置，所有拦截器都会自动加springdoc-opapi相关的资源排除信息，不用在应用程序自身拦截器定义的地方去添加，算是良心解耦实现。
*/
@SuppressWarnings("unchecked")
@Override
public void addInterceptors(InterceptorRegistry registry) {
try {
Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
if (registrations != null) {
for (InterceptorRegistration interceptorRegistration : registrations) {
interceptorRegistration.excludePathPatterns("/springdoc**/**");
}
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
Exemplo
Demonstração do projeto: springdoc-openapi
Renderização:
