SpringDoc openAPI 工具未扫描 Spring Boot 项目中的 API

Posted 2023-03-10

【中文标题】SpringDoc openAPI 工具未扫描 Spring Boot 项目中的 API

【英文标题】：SpringDoc openAPI tool not scanning for APIs in Spring Boot Project

【发布时间】：2020-05-12 06:44:44

【问题描述】：

我无法让它工作。我从一个工作正常的 SpringBoot (v2.2.2) 应用程序和一个工作的 @RestController 开始。为了让 springdoc 工作，我在我的 pom 中包含了以下依赖项：

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

然后我构建并启动了我的服务。然后我浏览到 api-docs 端点，我得到：

"openapi":"3.0.1","info":"title":"OpenAPI definition","version":"v0","servers":["url":"http://localhost:8081","description":"Generated server url"],"paths":,"components":

我错过了一步吗？我假设在运行时它会扫描我的代码，找到@RestController，找到@RequestMapping 方法并从中生成api。

作为第二次尝试，我决定用大张旗鼓的@Operation 注释来注释我的一个方法，但仍然没有得到响应。

最后，我尝试使用 springdoc.packagesToScan 手动指定带有我的控制器的包，但这也不起作用。

这感觉就像 springdoc 没有看到我的 Controller.. 即使 spring 看到了.. 它非常活跃并且可以工作..

不知道我错过了什么..

这是我的项目依赖项：

[INFO] +- org.springframework.boot:spring-boot-starter-web:jar:2.2.2.RELEASE:compile
[INFO] |  +- org.springframework.boot:spring-boot-starter:jar:2.2.2.RELEASE:compile
[INFO] |  |  +- org.springframework.boot:spring-boot:jar:2.2.2.RELEASE:compile
[INFO] |  |  +- org.springframework.boot:spring-boot-autoconfigure:jar:2.2.2.RELEASE:compile
[INFO] |  |  +- org.springframework.boot:spring-boot-starter-logging:jar:2.2.2.RELEASE:compile
[INFO] |  |  |  +- ch.qos.logback:logback-classic:jar:1.2.3:compile
[INFO] |  |  |  |  \- ch.qos.logback:logback-core:jar:1.2.3:compile
[INFO] |  |  |  +- org.apache.logging.log4j:log4j-to-slf4j:jar:2.12.1:compile
[INFO] |  |  |  |  \- org.apache.logging.log4j:log4j-api:jar:2.12.1:compile
[INFO] |  |  |  \- org.slf4j:jul-to-slf4j:jar:1.7.29:compile
[INFO] |  |  +- jakarta.annotation:jakarta.annotation-api:jar:1.3.5:compile
[INFO] |  |  \- org.yaml:snakeyaml:jar:1.25:compile
[INFO] |  +- org.springframework.boot:spring-boot-starter-json:jar:2.2.2.RELEASE:compile
[INFO] |  |  +- com.fasterxml.jackson.core:jackson-databind:jar:2.10.1:compile
[INFO] |  |  |  +- com.fasterxml.jackson.core:jackson-annotations:jar:2.10.1:compile
[INFO] |  |  |  \- com.fasterxml.jackson.core:jackson-core:jar:2.10.1:compile
[INFO] |  |  +- com.fasterxml.jackson.datatype:jackson-datatype-jdk8:jar:2.10.1:compile
[INFO] |  |  +- com.fasterxml.jackson.datatype:jackson-datatype-jsr310:jar:2.10.1:compile
[INFO] |  |  \- com.fasterxml.jackson.module:jackson-module-parameter-names:jar:2.10.1:compile
[INFO] |  +- org.springframework.boot:spring-boot-starter-tomcat:jar:2.2.2.RELEASE:compile
[INFO] |  |  +- org.apache.tomcat.embed:tomcat-embed-core:jar:9.0.29:compile
[INFO] |  |  +- org.apache.tomcat.embed:tomcat-embed-el:jar:9.0.29:compile
[INFO] |  |  \- org.apache.tomcat.embed:tomcat-embed-websocket:jar:9.0.29:compile
[INFO] |  +- org.springframework.boot:spring-boot-starter-validation:jar:2.2.2.RELEASE:compile
[INFO] |  |  +- jakarta.validation:jakarta.validation-api:jar:2.0.1:compile
[INFO] |  |  \- org.hibernate.validator:hibernate-validator:jar:6.0.18.Final:compile
[INFO] |  |     +- org.jboss.logging:jboss-logging:jar:3.4.1.Final:compile
[INFO] |  |     \- com.fasterxml:classmate:jar:1.5.1:compile
[INFO] |  +- org.springframework:spring-web:jar:5.2.2.RELEASE:compile
[INFO] |  |  \- org.springframework:spring-beans:jar:5.2.2.RELEASE:compile
[INFO] |  \- org.springframework:spring-webmvc:jar:5.2.2.RELEASE:compile
[INFO] |     +- org.springframework:spring-aop:jar:5.2.2.RELEASE:compile
[INFO] |     +- org.springframework:spring-context:jar:5.2.2.RELEASE:compile
[INFO] |     \- org.springframework:spring-expression:jar:5.2.2.RELEASE:compile
[INFO] +- com.google.guava:guava:jar:28.1-jre:compile
[INFO] |  +- com.google.guava:failureaccess:jar:1.0.1:compile
[INFO] |  +- com.google.guava:listenablefuture:jar:9999.0-empty-to-avoid-conflict-with-guava:compile
[INFO] |  +- com.google.code.findbugs:jsr305:jar:3.0.2:compile
[INFO] |  +- org.checkerframework:checker-qual:jar:2.8.1:compile
[INFO] |  +- com.google.errorprone:error_prone_annotations:jar:2.3.2:compile
[INFO] |  +- com.google.j2objc:j2objc-annotations:jar:1.3:compile
[INFO] |  \- org.codehaus.mojo:animal-sniffer-annotations:jar:1.18:compile
[INFO] +- org.apache.commons:commons-lang3:jar:3.9:compile
[INFO] +- org.springdoc:springdoc-openapi-ui:jar:1.2.28:compile
[INFO] |  +- org.springdoc:springdoc-openapi-webmvc-core:jar:1.2.28:compile
[INFO] |  |  \- org.springdoc:springdoc-openapi-common:jar:1.2.28:compile
[INFO] |  |     +- io.swagger.core.v3:swagger-models:jar:2.1.1:compile
[INFO] |  |     +- io.swagger.core.v3:swagger-annotations:jar:2.1.1:compile
[INFO] |  |     \- io.swagger.core.v3:swagger-integration:jar:2.1.1:compile
[INFO] |  |        \- io.swagger.core.v3:swagger-core:jar:2.1.1:compile
[INFO] |  |           +- javax.xml.bind:jaxb-api:jar:2.3.1:compile
[INFO] |  |           |  \- javax.activation:javax.activation-api:jar:1.2.0:compile
[INFO] |  |           +- com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:jar:2.10.1:compile
[INFO] |  |           \- javax.validation:validation-api:jar:2.0.1.Final:compile
[INFO] |  +- org.webjars:swagger-ui:jar:3.24.3:compile
[INFO] |  \- org.webjars:webjars-locator:jar:0.38:compile
[INFO] |     \- org.webjars:webjars-locator-core:jar:0.41:compile
[INFO] |        +- io.github.classgraph:classgraph:jar:4.8.44:compile
[INFO] |        \- org.webjars.npm:angular__http:jar:2.4.10:compile
[INFO] +- org.assertj:assertj-core:jar:3.14.0:test
[INFO] \- org.springframework.boot:spring-boot-starter-test:jar:2.2.2.RELEASE:test
[INFO]    +- org.springframework.boot:spring-boot-test:jar:2.2.2.RELEASE:test
[INFO]    +- org.springframework.boot:spring-boot-test-autoconfigure:jar:2.2.2.RELEASE:test
[INFO]    +- com.jayway.jsonpath:json-path:jar:2.4.0:test
[INFO]    |  +- net.minidev:json-smart:jar:2.3:test
[INFO]    |  |  \- net.minidev:accessors-smart:jar:1.2:test
[INFO]    |  |     \- org.ow2.asm:asm:jar:5.0.4:test
[INFO]    |  \- org.slf4j:slf4j-api:jar:1.7.29:compile
[INFO]    +- jakarta.xml.bind:jakarta.xml.bind-api:jar:2.3.2:test
[INFO]    |  \- jakarta.activation:jakarta.activation-api:jar:1.2.1:test
[INFO]    +- org.junit.jupiter:junit-jupiter:jar:5.5.2:test
[INFO]    |  +- org.junit.jupiter:junit-jupiter-api:jar:5.5.2:test
[INFO]    |  |  +- org.opentest4j:opentest4j:jar:1.2.0:test
[INFO]    |  |  \- org.junit.platform:junit-platform-commons:jar:1.5.2:test
[INFO]    |  +- org.junit.jupiter:junit-jupiter-params:jar:5.5.2:test
[INFO]    |  \- org.junit.jupiter:junit-jupiter-engine:jar:5.5.2:test
[INFO]    +- org.junit.vintage:junit-vintage-engine:jar:5.5.2:test
[INFO]    |  +- org.apiguardian:apiguardian-api:jar:1.1.0:test
[INFO]    |  +- org.junit.platform:junit-platform-engine:jar:1.5.2:test
[INFO]    |  \- junit:junit:jar:4.12:test
[INFO]    +- org.mockito:mockito-junit-jupiter:jar:3.1.0:test
[INFO]    +- org.hamcrest:hamcrest:jar:2.1:test
[INFO]    +- org.mockito:mockito-core:jar:3.1.0:test
[INFO]    |  +- net.bytebuddy:byte-buddy:jar:1.10.4:test
[INFO]    |  +- net.bytebuddy:byte-buddy-agent:jar:1.10.4:test
[INFO]    |  \- org.objenesis:objenesis:jar:2.6:test
[INFO]    +- org.skyscreamer:jsonassert:jar:1.5.0:test
[INFO]    |  \- com.vaadin.external.google:android-json:jar:0.0.20131108.vaadin1:test
[INFO]    +- org.springframework:spring-core:jar:5.2.2.RELEASE:compile
[INFO]    |  \- org.springframework:spring-jcl:jar:5.2.2.RELEASE:compile
[INFO]    +- org.springframework:spring-test:jar:5.2.2.RELEASE:test
[INFO]    \- org.xmlunit:xmlunit-core:jar:2.6.3:test

这是我的项目的树。它是一个标准的 spring boot 结构。控制器在 web dir/package 下

.
├── java
│   └── com
│       └── neodem
│           └── orl
│               ├── collections
│               ├── config
│               ├── engine
│               │   ├── core
│               │   │   ├── actions
│               │   │   └── model
│               │   └── original
│               │       ├── actions
│               │       └── model
│               ├── service
│               └── web
└── resources

【问题讨论】：

你能展示一下你的包装结构吗？

谢谢，但我的意思是你的项目结构

控制器类在web包下？如果是，请您将网络名称更改为控制器并再次测试

请添加 springdoc.packagesToScan 配置，我在答案中添加了它作为解决方案 3，请测试它

我已经进行了两项更改.. 没有运气/相同的结果：你能告诉我扫描应该如何工作吗？文档中不清楚

【参考方案1】：

它是： 而不是：

@GetMapping(BookConfig.BOOK_ENDPOINT)

你必须这样做：

@RequestMapping(值 = BookConfig.BOOK_ENDPOINT, 方法 = RequestMethod.GET)

这是发现根本原因的一大痛苦。 OpenAPI 需要增强其框架以支持 Spring 的最新注解版本。它实际上已经存在了很长一段时间。 减少打字是要走的路。

【参考方案2】：

只是补充一点，我遇到了同样的问题，并通过将 @Controller 替换为 @RestController 来解决。

【讨论】：

我使用 @RestController 并在我的 pom 添加 springdoc-openapi-ui 依赖项后仍然得到 404

【参考方案3】：

我在我的案例中找到了解决方案，并发布了 springdoc git 问题 (https://github.com/springdoc/springdoc-openapi/issues/378)。它（部分）内容为：

当定义一个 REST 控制器时，spring 允许你声明 @RequestMapping(value = "/init") 没有明确的方法，并且会接受一个 POST 请求。但是，在您的OpenApiResource 类中，您调用了calculatePath，在那里（在第129 行）您调用了弹簧RequestMappingInfo.getMethodsCondition()，在我的情况下，您没有得到任何结果（因为没有明确定义该方法在注释中）..因此没有请求方法=>没有计算路径。

如果我明确定义方法：@RequestMapping(value = "/init", method = RequestMethod.POST) 一切都按预期工作。

所以解决方案是在@RequestMapping中显式声明方法

【讨论】：

这看起来像一个糟糕的 API 设计。如果您没有定义 HTTP 方法，则意味着您的 API 接受所有 HTTP 方法。它真的是您想要向客户公开的那种 API 吗？

受害者在软件中指责...耶

这毫无意义。如果您的控制器有 GET、PUT、POST、DELETE... 请求（@GetMapping、@PutMapping、@PostMapping、@DeleteMapping...）怎么办？你怎么能明确地用method = RequestMethod.POST标记它。

【参考方案4】：

这是因为您使用的是springdoc-openapi-ui，当您想将springdoc-openapi与Swagger UI集成时使用它，因此您应该首先添加并启用Swagger UI来检查结果 然后检查招摇链接。喜欢：http://localhost:8080/swagger-ui.html。

如果你不想招摇，你必须使用springdoc-openapi-core 而不是springdoc-openapi-ui。

总结

解决方案 1

添加和启用 Swagger UI 检查 Swagger 网址 (server-address:port/swagger-ui.html.)

解决方案 2

将依赖关系从 springdoc-openapi-ui 更改为 springdoc-openapi-core

你的依赖必须像下面的 sn-p:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-core</artifactId>
    <version>1.1.44</version>
</dependency>

解决方案 3

通过配置列出要包含在文档中的包

#Packages to include
springdoc.packagesToScan=com.neodem.orl.web

还有 This link 可能有用。 （使用 springdoc-openapi 记录 Spring REST API）

【讨论】：

谢谢。我发现 baeldung 链接有点过时了，因为 springdoc 项目不再使用 -core 包，他们已经将它包含在 springdoc-openapi-ui 包中。我想使用springdoc-openapi-ui 和swagger ui，这确实有效，但当然它说“规范中没有定义操作！”

另外，我应该补充一点，当我按照 baeldung 说明并使用 springdoc-openapi-core 包时，我得到了相同的结果..（未识别 API，未扫描控制器）