api开发框架 java openapi开发框架

OpenAPI使用（swagger3）

demo见Gitte

一、背景及名词解释

OpenAPI是规范的正式名称。规范的开发工作于2015年启动，当时SmartBear（负责Swagger工具开发的公司）将Swagger 2.0规范捐赠给了Open API Initiative，该协会由来自技术领域不同领域的30多个组织组成。此后，该规范被重命名为OpenAPI规范。 Swagger 是一个 API文档维护组织，后来成为了 Open API 标准的主要定义者。现在最新的版本为17年发布的 Swagger3（Open Api3）。 是一个Open API规范实现工具包，由于Swagger工具是由参与创建原始Swagger规范的团队开发的，因此通常仍将这些工具视为该规范的代名词。目前可以认为Swagger3就是Open API 3.0 OpenAPI 3.0：2017年7月，Open API Initiative最终发布了OpenAPI Specification 3.0.0。它对2.0规范进行了很多改进。Open API 3.0规范可以用JSON或YAML编写，并且在记录RESTful API方面做得很好。同时标志着Swagger2成为过去式。 SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。截至2020年4月，尚未支持 OpenAPI3 标准。 SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。 也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用

二、整合springdoc-openapi

maven的话，在pom.xml里面去掉springfox，添加如下的openapi依赖。

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

gradle的话 build.gradle.kts中添加

implementation("org.springdoc:springdoc-openapi-ui:1.5.2")

就这么简单，文档就构建完成了，不需要做任何的其他配置。 访问：http://ip:port/swagger-ui.html

三、将API分组分组展示

配置方法 java:

@Configuration
public class OpenAPIConfig {

@Bean
public GroupedOpenApi restApi() {
return GroupedOpenApi.builder()
.group("rest-api")
.pathsToMatch("/rest/**")
.build();
}

@Bean
public GroupedOpenApi helloApi() {
return GroupedOpenApi.builder()
.group("hello")
.pathsToMatch("/hello/**")
.build();
}


}

kotlin:

@Configuration
class OpenAPIConfig {
    @Bean
    fun restApi(): GroupedOpenApi {
        return GroupedOpenApi.builder()
            .group("rest-api")
            .pathsToMatch("/rest/**")
            .build()
    }

    @Bean
    fun helloApi(): GroupedOpenApi {
        return GroupedOpenApi.builder()
            .group("hello")
            .pathsToMatch("/hello/**")
            .build()
    }
}

显示效果,通过下拉选择分组，查看组内API

四、使用 swagger3 注解代替 swagger2注解

如果你希望为文档加上更详细的中文注释，使用如下注解（对比Swagger2注解使用方法使用即可）。但是笔者觉得没有必要学习这东西，意义不大。注意变量、接口命名规范，英文的接口文档就挺好。 用 swagger 3 的注解（已经在上面maven包引入）代替 swagger 2 的注解，swagger 3 注解的包路径为io.swagger.v3.oas.annotations。

四、常见问题

api写入分组后未展示：
解决方法：放入数组后再使用，见这里

---

更多内容指引官网：https://springdoc.org/