OpenApi 接口文档

1.统一的API接口平台

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

基于OpenAPI规范只适用于MVC框架，不适用integration框架。

2.OpenAPI

        OpenAPI 规范（OpenAPI Specification简称OAS），是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好，那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

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

OpenAPI 规范 (中文版)

 3. Swagger

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

Swagger工具包括的组件：

• Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。
• Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。
• Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。
• Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
• Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

3API Documentation & Design Tools for Teams | Swagger

4. Springfox

        是Spring生态的一个开源库，是Swagger与OpenApi规范的具体实现。我们使用它就可以在spring中生成API文档。Springfox提供了一些注解来描述API接口、参数和返回值，并根据这些信息生成Swagger UI界面，从而方便其他开发人员查看和使用您的API接口。新版本可以支持 Swagger2, Swagger3 以及 OpenAPI3 三种格式。从 2020年7月14号就不再更新了，不支持springboot3。

SpringFox by springfox

4. SpringDoc

        SpringDoc是基于OpenAPI 3.0规范构建的，推荐在Spring Boot 2.4及以上版本中使用springdoc-openapi-ui库来集成Swagger3.x。在这些版本中，springdoc-openapi-ui库已被广泛应用，并且得到了社区的大力支持和推广。而在Spring Boot 2.3及其以下版本，可以使用springfox-boot-starter库来集成Swagger2.x。新项目推荐使用springdoc

5. SpringBoot使用Springfox

添加依赖：

        <!--swagger 3.0.0-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

增加配置类：

@Configuration
public class Swagger2Config {

    @Bean
    public Docket docketGroup1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("public group")
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.basePackage("com.lx.lxbootweb"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket docketGroup2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("internal group")
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }


    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "title 1",
                "this is first api",
                "1.0",
                "termsOfServiceUrl",
                new Contact("name", "url", "eamil"),
                "license"
                , "licenseUrl"
                , Collections.emptyList()
        );
        return apiInfo;
    }
}

 swagger 3.0.0访问：http://localhost:8080/swagger-ui/index.html

6. SpringBoot使用Springdoc

增加依赖

        <!--springdoc-->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.8.0</version>
        </dependency>

springdoc有默认配置所以不需要配置，就能扫描到当前项目的restful 接口。直接访问http://localhost:8080/swagger-ui/index.html就可以查看接口文档。

自定义配置：

@Configuration
public class CustomizeSpringDoc {

    @Bean
    public OpenAPI myOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("titele sprngdoc")
                        .description("this is springdoc")
                        .version("v1.0.0")
                        .license(new License()
                                .name("许可协议")
                                .url("https://url"))
                        .contact(new Contact()
                                .name("contact name")
                                .email("email.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("csdn博客")
                        .url("https://csdn.com"));
    }

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public api")
                .packagesToScan("com.lx.lxbootweb")
                .pathsToMatch("/**")
                .build();
    }

    @Bean
    public GroupedOpenApi internalApi() {
        return GroupedOpenApi.builder()
                .group("internal api")
                .pathsToMatch("/**")
                .build();
    }
}

参考：

秒懂SpringBoot之如何集成SpringDoc（全网目前最新最系统最全面的springdoc教程） - 知乎