Spring Boot 3.x- RESTful API集成SpringDoc&Swagger-UI

系列文章目录

系列文章:Spring Boot 3.x 系列教程



前言

springdoc-openapi 帮助使用Spring Boot项目自动化API文档的生成。springdoc-openapi的工作原理是在运行时检查应用程序,根据Spring配置、类结构和各种注释推断API语义。
自动生成JSON/YAMLHTML格式的API文档。这个文档可以通过使用swagger-api注解来完成。

官方网站:springdoc.org

由于Spring Boot 3使用的是Jakarta EE 9,对应的springdoc版本需要升级到v2,目前里程碑M2版本。支持以下内容:

  • OpenAPI 3
  • Spring-boot v3 (Java 17 & Jakarta EE 9)
  • JSR-303 特别注解 @NotNull, @Min, @Max, 和 @Size.
  • Swagger-ui
  • OAuth 2
  • GraalVM native images

Swagger2已经在17年停止维护了,取而代之的是 Swagger3(基于OpenAPI 3),OpenApi是业界真正的 api 文档标准,其是由 Swagger 来维护。

这是一个基于社区的项目,不是由Spring Framework贡献者(Pivotal)维护的。


一、快速开始

为了集成spring-bootswagger-ui,将下列依赖添加到你项目即可(不需要额外的配置)。

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.0-M2</version>
   </dependency>

这样自动将swagger-ui部署到一个spring-boot应用程序:

  1. 使用官方的swagger-ui jar,可以获得HTML格式的文档

  2. Swagger UI页面地址http://server:port/context-path/swagger-ui.htmlOpenAPI描述将在以下json格式的url上可用:http://server:port/context-path/v3/api-docs

例如:http://localhost:8080/swagger-ui.html http://localhost:8080/v3/-api-docs

  1. 文档也可以以yaml格式提供,位于以下路径:/v3/api-docs.yaml

对于HTML格式的swagger文档的自定义路径,在spring-boot配置文件中添加一个自定义springdoc属性:。
springdoc.swagger-ui.path=/swagger-ui.html

二、Springdoc-openapi模块

在这里插入图片描述

Spring WebMvc支持

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
      <version>2.0.0-M2</version>
   </dependency>

Spring WebFlux 支持

 <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
      <version>2.0.0-M2</version>
   </dependency>

三、Restful Api服务集成

本节已Spring Boot3 Restful Api服务为例集成。

1.在原有项目基础上加入 SpringDoc webmvc依赖
2.启动项目
3.访问http://localhost:8080/swagger-ui/index.html
在这里插入图片描述

基础配置

1.接口文档全局基础信息配置。

/**
 * spring doc配置
 */
@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI restfulOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Spring Boot3 Restful Zoo API")
                        .description("Zoo & Animal Detail APi")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringDoc Wiki Documentation")
                        .url("https://springdoc.org/v2"));
    }

}

2.重启项目,接口文档展示具体的描述以及开源协议和wiki地址。
在这里插入图片描述
3.接口描述和字段描述
默认情况下接口的功能描述和参数以及字段描述都为空,需要添加对应的注解SpringDoc才能解析:
在这里插入图片描述

在swagger2中SpringFox项目使用非常广泛,它也是让spring boot项目快速的集成swagger。目前此项目已经停止更新。那么他们直接注解的对应关系如下:

@Api@Tag
@ApiIgnore@Parameter(hidden = true) or @Operation(hidden = true) or @Hidden

@ApiImplicitParam@Parameter

@ApiImplicitParams@Parameters

@ApiModel@Schema

@ApiModelProperty(hidden = true)@Schema(accessMode = READ_ONLY)

@ApiModelProperty@Schema

@ApiOperation(value = "foo", notes = "bar")@Operation(summary = "foo", description = "bar")

@ApiParam@Parameter

@ApiResponse(code = 404, message = "foo")@ApiResponse(responseCode = "404", description = "foo")

下面已ZooController为例:

@Tag 描述整个Controller

@Tag(name = "ZooController", description = "动物园API")
@RestController
@RequestMapping("/zoos")
public class ZooController {}

@Operation描述具体接口信息,@Parameter描述参数信息 @ApiResponse 接口响应描述信息

  //描述具体接口信息,参数信息
    @Operation(summary = "获取动物园详情", description = "返回单个对象",
            parameters = {@Parameter(name = "id", description = "动物园id")})
    @ApiResponse(responseCode = "2xx",description = "动物园实体对象")
    @SneakyThrows
    @GetMapping(value = "/{id}")
    public ResponseEntity<ZooResponse> detail(@PathVariable("id") Integer id) {

        return ResponseEntity.ok(zooService.detail(id));
    }

@Schema 描述对象信息

@Data
@NoArgsConstructor
@AllArgsConstructor
@Schema(name = "ZooResponse", title = "动物园对象")
public class ZooResponse implements Serializable {
    @Schema(title = "动物园id")
    private Integer id;
    @Schema(title = "动物园名称")
    private String name;
    @Schema(title = "动物园地址")
    private String address;
    @Schema(title = "动物园电话")
    private String telephone;
}

在这里插入图片描述

在这里插入图片描述


总结

SpringDoc集成Swagger到Spring Boot3 非常的方便,目前2者都是m2版本,等待最终GA版本。


版权声明:本文为renpeng301原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
THE END
< <上一篇
下一篇>>