Swagger、OpenAPI和springdoc-openapi-ui

一、概念熟悉

Swagger

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

OpenAPI

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

springdoc-openapi-ui

github地址：GitHub - springdoc/springdoc-openapi: Library for OpenAPI 3 with spring-boot

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.

springdoc-openapi lib可以帮助Spring Boot projects自动生成API文档；springdoc-openapi 的工作机制是基于 Spring 配置、类结构和各种注释，在运行时检查应用程序，推断 API 语义。

The springdoc-openapi会自动生成 JSON/YAML 和 HTML 格式的文档。生成的文档可以使用 swagger-api 注释进行补充。

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

二、Swagger使用

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

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
</dependency>

三、springdoc-openapi-ui使用

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

        <dependency>

            <groupId>org.springdoc</groupId>

            <artifactId>springdoc-openapi-ui</artifactId>

            <version>xxx</version>

        </dependency>

（2）常用注解说明

• @OpenAPIDefinition在springboot之中只会生效一个，用于描述该服务的全局信息；
• @Tag可以加在类和方法上，swagger2中controller会自动加上，用来在页面中显示某个接口属于某个controller，在这里需要手动加上；
• @Operation，主要用来描述一些接口的信息；
• @Parameter用来描述一些传入参数的信息，这种方式则是把参数都放在了 @Operation之中，in可以指定参数来源；

• @Schema可以注解实体类，swagger页面上显示实体类的信息

四、springdoc实战

涉及实际项目信息，待去密后补充