跳至主要內容

29. RESTful API 集成 SpringDoc&Swagger-UI

安图新大约 3 分钟

29. RESTful API 集成 SpringDoc&Swagger-UI

前言

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

官方网站:springdoc.orgopen in new window

由于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-uijar,可以获得HTML格式的文档;
2、 SwaggerUI 页面地址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 服务open in new window为例集成。

1、 在原有项目基础上加入 SpringDocwebmvc 依赖;
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 版本。