OpenAPI-Swagger3-介绍使用

Posted jinyuanya

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了OpenAPI-Swagger3-介绍使用相关的知识,希望对你有一定的参考价值。

OpenAPI

是一个规范的名称。

3.0版本的对RESTful API方面做得很好。

Swagger

是一个 API文档维护组织,后来成为了 Open API 标准的主要定义者。现在最新的版本为17年发布的 Swagger3(Open Api3)。

是一个Open API规范实现工具包,由于Swagger工具是由参与创建原始Swagger规范的团队开发的,因此通常仍将这些工具视为该规范的代名词。目前可以认为Swagger3就是Open API 3.0

SpringFox

是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用。截至2020年4月,尚未支持 OpenAPI3 标准。

SpringDoc

也是 spring 社区维护的一个项目(非官方),帮助使用者将 swagger3 集成到 Spring 中。

也是用来在 Spring 中帮助开发者生成文档,并可以轻松的在spring boot中使用

整合springdoc-openapi

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

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

就这么简单,文档就构建完成了,不需要做任何的其他配置。

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

技术图片

三、将API分组分组展示

配置方法

@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();
  }


}

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

技术图片

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

如果你希望为文档加上更详细的中文注释,使用如下注解(对比Swagger2注解使用方法使用即可)。但是笔者觉得没有必要学习这东西,意义不大。注意变量、接口命名规范,英文的接口文档就挺好。

用 swagger 3 的注解(已经在上面maven包引入)代替 swagger 2 的注解,swagger 3 注解的包路径为io.swagger.v3.oas.annotations。

Swagger2注解 OpenAPI3(swagger3)注解
@ApiParam @Parameter
@ApiOperation @Operation
@Api @Tag
@ApiImplicitParams @Parameters
@ApiImplicitParam @Parameter
@ApiIgnore @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
@ApiModel @Schema
@ApiModelProperty @Schema

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

以上是关于OpenAPI-Swagger3-介绍使用的主要内容,如果未能解决你的问题,请参考以下文章

Jacoco和Tycho surefire的Eclipse RCP插件代码介绍

使用 Git 来管理 Xcode 中的代码片段

sublime 3 使用Snippets创建代码片段

48个值得掌握的JavaScript代码片段(上)

从零开始配置vim(27)——代码片段

从零开始配置vim(27)——代码片段