使用 springdoc-openapi 和 spring-boot-starter-data-mongodb 生成 OpenAPI 文档
Posted
技术标签:
【中文标题】使用 springdoc-openapi 和 spring-boot-starter-data-mongodb 生成 OpenAPI 文档【英文标题】:Generating OpenAPI documentation using springdoc-openapi with spring-boot-starter-data-mongodb 【发布时间】:2020-04-02 02:00:14 【问题描述】:我已经使用 MongoDB 启动了一个新的 Spring Boot 应用程序 (2.2.1.RELEASE)。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-rest</artifactId>
</dependency>
为了创建一些 API 文档,我添加了 springdoc-api:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.1.49</version>
</dependency>
由于我依赖 Spring 来处理 REST 端点的生成,因此我创建了这个简单的存储库:
@RepositoryRestResource(collectionResourceRel = "profile", path = "profile")
public interface ProfileRepository extends MongoRepository<Profile, String>
List<Profile> findByLastname(@Param("n") String lastname);
List<Profile> findByFirstname(@Param("n") String firstname);
List<Profile> findByEmail(@Param("e") String email);
所以我没有@RestController
的课程。
我尝试在ProfileRepository
中的方法中添加一些io.swagger.v3.oas.annotations
注释,但没有生成任何内容。
@Operation(summary = "Find Profile by first name", description = "Find Profile by first name")
List<Profile> findByLastname(@Param("n") String lastname);
http://localhost:8080/v3/api-docs/
的结果:
"openapi": "3.0.1",
"info":
"title": "OpenAPI definition",
"version": "v0"
,
"servers": [
"url": "http://localhost:8080",
"description": "Generated server url"
],
"paths": ,
"components":
如何为我的 Spring Data REST 存储库端点生成 API 文档?
【问题讨论】:
你能解决这个问题吗?它可能不受支持(请参阅github.com/springdoc/springdoc-openapi/issues/298)。也相关;我自己关于这个话题的问题:***.com/questions/59868163/… 【参考方案1】:根据这个问题:https://github.com/springdoc/springdoc-openapi/issues/282,不可能从spring-boot-starter-data-rest
生成 OpenAPI 文档,因为
spring-data-rest 实体端点在运行时动态生成 [...]
在上述 GitHub 问题上引用用户“bnasslahsen”。
【讨论】:
这个问题已被删除,虽然它存在于archive.org:web.archive.org/web/20201217021135/https://github.com/springdoc/…【参考方案2】:从 springdoc-openapi 1.2.11 版开始,添加 org.springdoc:springdoc-openapi-data-rest
依赖项将为 Spring Data REST 端点生成 API 文档。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-data-rest</artifactId>
<version>1.5.10</version>
</dependency>
【讨论】:
以上是关于使用 springdoc-openapi 和 spring-boot-starter-data-mongodb 生成 OpenAPI 文档的主要内容,如果未能解决你的问题,请参考以下文章
springdoc-openapi 应用默认全局 SecurityScheme 可能吗?
springdoc-openapi 如何在不更改 toString 的情况下使用 @JsonValue 枚举格式?
springdoc-openapi swagger-ui 中的 CSRF 支持
springdoc-openapi 在没有服务器的情况下生成 openapi yaml
使用sp_addlinkedserversp_dropserver sp_addlinkedsrvlogin和sp_droplinkedsrvlogin 远程查询数据