Swagger、OpenAPI和springdoc-openapi-ui入门

统一的API接口平台

有了统一的API接口平台，不管对内还是对外，都能更好做到：统一接口开发、统一接口管理、统一接口开放服务。统一接口开发：包括API接口的命名、分类、格式、接口文档、接口变更记录、接口发布、接口测试、接口日记等，都要统一风格、规范标准和约束。统一接口管理：包括API接口的升级、增加参数、部署、性能监控、错误日志，同时结合开发、测试、运维、文档等形成整套的研发体系和闭环。统一接口开放服务：主要是针对接口的IP白名单、接口申请、接口调用权限、接口次数限制、接口流量统计，以及开发者账号的开通注册，以应用的创建和审核。解决要不要对接口收费，怎么收费和进行服务、售后支持。

概念认知

Swagger：���一种用于描述RESTFUL API的规范，它提供了一种简单的来描述API的请求和相应参数、错误码、返回数据类型等信息，是开发者可以方便了解API使用方式。

OpenAPI 始于 Swagger 规范，Swagger 规范已于 2015 年捐赠给 Linux 基金会后改名为 OpenAPI，并定义最新的规范为 OpenAPI 3.0。

OpenAPI 规范（OAS）是一种通用的、和编程语言无关的 API 描述规范，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码、文档或针对接口进行嗅探。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。

springdoc-openapi-ui：https://github.com/springdoc/springdoc-openapi

The springdoc-openapi Java library helps automating the generation of API documentation using Spring Boot projects. springdoc-openapi works by examining an application at runtime to infer API semantics based on Spring configurations, class structure and various annotations.

The library automatically generates documentation in JSON/YAML and HTML formatted pages. The generated documentation can be complemented using swagger-api annotations.

maven地址：https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

swagger2与swagger3(springdoc)常用注解对比

Swagger入门

普通SpringBoot项目中在pom.xml中引入jar包

        io.springfox        springfox-swagger2        2.9.2                io.springfox        springfox-swagger-ui        2.9.2    `在这里插入代码片`    

构建SwaggerConfig

package com.ca.web.core.config;import java.util.ArrayList;import java.util.List;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.beans.factory.annotation.Value;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import com.ca.common.config.RuoYiConfig;import io.swagger.annotations.ApiOperation;import io.swagger.models.auth.In;import org.springframework.web.servlet.config.annotation.EnableWebMvc;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.ApiKey;import springfox.documentation.service.AuthorizationScope;import springfox.documentation.service.Contact;import springfox.documentation.service.SecurityReference;import springfox.documentation.service.SecurityScheme;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spi.service.contexts.SecurityContext;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;/** * Swagger2的接口配置 *  * @author ruoyi */@Configuration@EnableWebMvc@EnableSwagger2public class SwaggerConfig{    /**     * 创建API     */    @Bean    public Docket createRestApi()    {        return new Docket(DocumentationType.SWAGGER_2)                // 设置哪些接口暴露给Swagger展示                .select()                // 扫描所有有注解的api，用这种方式更灵活                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                .build();    }}

springdoc-openapi-ui入门

（1）springboot工程pom依赖

                    org.springdoc            springdoc-openapi-ui            xxx        

（2）SwaggerProperties

@ConfigurationProperties("xxx.swagger")@Datapublic class SwaggerProperties {    /**     * 标题     */    @NotEmpty(message = "标题不能为空")    private String title;    /**     * 描述     */    @NotEmpty(message = "描述不能为空")    private String description;    /**     * 作者     */    @NotEmpty(message = "作者不能为空")    private String author;    /**     * 版本     */    @NotEmpty(message = "版本不能为空")    private String version;    /**     * url     */    @NotEmpty(message = "扫描的 package 不能为空")    private String url;    /**     * email     */    @NotEmpty(message = "扫描的 email 不能为空")    private String email;    /**     * license     */    @NotEmpty(message = "扫描的 license 不能为空")    private String license;    /**     * license-url     */    @NotEmpty(message = "扫描的 license-url 不能为空")    private String licenseUrl;}

(3)SwaggerAutoConfiguration

@AutoConfiguration@ConditionalOnClass({OpenAPI.class})@EnableConfigurationProperties(SwaggerProperties.class)@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", havingValue = "true", matchIfMissing = true) // 设置为 false 时，禁用public class SwaggerAutoConfiguration {    // ========== 全局 OpenAPI 配置 ==========    @Bean    public OpenAPI createApi(SwaggerProperties properties) {        Map securitySchemas = buildSecuritySchemes();        OpenAPI openAPI = new OpenAPI()                // 接口信息                .info(buildInfo(properties))                // 接口安全配置                .components(new Components().securitySchemes(securitySchemas))                .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));        securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));        return openAPI;    }    /**     * API 摘要信息     */    private Info buildInfo(SwaggerProperties properties) {        return new Info()                .title(properties.getTitle())                .description(properties.getDescription())                .version(properties.getVersion())                .contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))                .license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));    }    /**     * 安全模式，这里配置通过请求头 Authorization 传递 token 参数     */    private Map buildSecuritySchemes() {        Map securitySchemes = new HashMap();        SecurityScheme securityScheme = new SecurityScheme()                .type(SecurityScheme.Type.APIKEY) // 类型                .name(HttpHeaders.AUTHORIZATION) // 请求头的 name                .in(SecurityScheme.In.HEADER); // token 所在位置        securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);        return securitySchemes;    }    /**     * 自定义 OpenAPI 处理器     */    @Bean    public OpenAPIService openApiBuilder(Optional openAPI,                                         SecurityService securityParser,                                         SpringDocConfigProperties springDocConfigProperties,                                         PropertyResolverUtils propertyResolverUtils,                                         Optional openApiBuilderCustomizers,                                         Optional serverBaseUrlCustomizers,                                         Optional javadocProvider) {        return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,                propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);    }    // ========== 分组 OpenAPI 配置 ==========    /**     * 所有模块的 API 分组     */    @Bean    public GroupedOpenApi allGroupedOpenApi() {        return buildGroupedOpenApi("all", "");    }    public static GroupedOpenApi buildGroupedOpenApi(String group) {        return buildGroupedOpenApi(group, group);    }    public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {        return GroupedOpenApi.builder()                .group(group)                .pathsToMatch("/admin-api/" + path + "/**", "/app-api/" + path + "/**")                .addOperationCustomizer((operation, handlerMethod) -> operation                        .addParametersItem(buildTenantHeaderParameter())                        .addParametersItem(buildSecurityHeaderParameter()))                .build();    }    /**     * 构建 Tenant 租户编号请求头参数     *     * @return 多租户参数     */    private static Parameter buildTenantHeaderParameter() {        return new Parameter()                .name(WebFrameworkUtils.HEADER_TENANT_ID) // header 名                .description("租户编号") // 描述                .in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header                .schema(new IntegerSchema()._default(1L).name(WebFrameworkUtils.HEADER_TENANT_ID).description("租户编号")); // 默认：使用租户编号为 1    }    /**     * 构建 Authorization 认证请求头参数     *     * 解决 Knife4j Authorize 未生效，请求header里未包含参数     *     * @return 认证参数     */    private static Parameter buildSecurityHeaderParameter() {        return new Parameter()                .name(HttpHeaders.AUTHORIZATION) // header 名                .description("认证 Token") // 描述                .in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header                .schema(new StringSchema()._default("Bearer test1").name(WebFrameworkUtils.HEADER_TENANT_ID).description("认证 Token")); // 默认：使用用户编号为 1    }}

(4)yaml文件配置

springdoc:  api-docs:    enabled: true    path: /v3/api-docs  swagger-ui:    enabled: true    path: /swagger-ui

（6）代码开发

package com.hello.api.admin;import com.hello.dto.CommonResult;import com.hello.dto.User;import io.swagger.v3.oas.annotations.Operation;import io.swagger.v3.oas.annotations.Parameter;import io.swagger.v3.oas.annotations.media.Content;import io.swagger.v3.oas.annotations.media.Schema;import io.swagger.v3.oas.annotations.responses.ApiResponse;import io.swagger.v3.oas.annotations.tags.Tag;@Tag(name = "AdminControllerApi", description = "管理员相关接口")public interface AdminControllerApi {    @Operation(summary = "管理员添加用户",            description = "根据姓名添加用户并返回",            parameters = {                    @Parameter(name = "name", description = "姓名")            },            responses = {                    @ApiResponse(description = "返回添加的用户", content = @Content(mediaType = "application/json", schema = @Schema(anyOf = {CommonResult.class, User.class}))),                    @ApiResponse(responseCode = "400", description = "返回400时候错误的原因")            }    )    CommonResult addUser(String name);    @Operation(summary = "管理员删除用户", description = "根据姓名删除用户")    @ApiResponse(description = "返回添加的用户", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))    CommonResult delUser(@Parameter(description = "姓名") String name);    @Operation(summary = "管理员更新用户", description = "管理员根据姓名更新用户")    @ApiResponse(description = "返回更新的用户", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))    CommonResult updateUser(@Parameter(schema = @Schema(implementation = User.class), required = true, description = "用户类") User user);}

（5）启动访问：127.0.0.1:8080/swagger-ui