Swagger OpenAPI 3.0 正在与 springdoc-openapi-ui 和自定义 OpenAPI Bean 配合使用。

pom.xml

<parent>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-parent</artifactId>
  <version>Hoxton.SR10</version>
</parent>
...
<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.5.5</version>
</dependency>

Swagger配置：

相同配置下spring-security的问题

当使用 springdoc-openapi-ui、springdoc-openapi-security 以及 spring-boot-starter-security 和 keycloak-spring-boot-starter 时，我们面临一个问题。

pom.xml

<dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-security</artifactId>
      <version>1.5.5</version>
</dependency>
<dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-spring-boot-starter</artifactId>
      <version>12.0.2</version>
</dependency>
<dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-security</artifactId>
      <version>2.4.2</version>
</dependency>

DummySecurityConfig（当前使用配置文件dev）：

@Profile({"test", "dev"})
@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(
        prePostEnabled = true,
        securedEnabled = true,
        jsr250Enabled = true)
@EnableWebMvc
public class DummySecurityConfig extends WebSecurityConfigurerAdapter implements WebMvcConfigurer {

    protected static final String[] ACTUATOR_WHITELIST = {
        "/actuator/**"
    };

    protected …

springdoc -openapi库会根据生成的 OpenAPI 文档中的要求自动标记某些属性。例如，注释为 的属性@NotNull将包含在生成的 YAML 文件的必需属性列表中。

该库不做的一件事是将可选属性标记为nullable: true. 但是，默认情况下，Spring Boot 应用程序将接受null请求并返回null可选属性的响应。这意味着 OpenAPI 文档和端点的行为之间存在差异。

手动将任何单个属性标记为可为空非常简单：只需添加@Schema(nullable = true)到字段或访问器即可。但是，在具有多个属性的大型模型中，我宁愿以与required属性相同的方式自动确定它。也就是说，如果不需要该属性，我希望它是nullable，反之亦然。

如何将我的可选属性标记为nullable: truespringdoc-openapi 生成的 OpenAPI 文档？

例子

import io.swagger.v3.oas.annotations.media.Schema;
import javax.validation.constraints.NotNull;

public class RequiredExample {
    @NotNull
    private String key;

    private String value;

    public String getKey() { return key; }
    public void setKey(String key) { this.key = key; }
    public String getValue() { return value; } …

我有一个带有 Spring Cloud Gateway 的微服务架构，每个微服务都有自己的 Open Api Spec。我需要将它们全部合并到 1 个开放 Api 规范（ yaml 或 json ）中。我不是在谈论服务多个链接的单个 swagger UI。我确实需要合并规范，因为规范的使用者需要一个 json 文件。此文件由 Atlassian 的 Open Api Validator 使用。

尝试在 Spring Cloud 网关级别为我的微服务实现 spring 文档。

遇到了这两个依赖项。想知道有什么区别

"springdoc-openapi-ui" vs "springdoc-openapi-webmvc-core"

和

"springdoc-openapi-ui" vs "springdoc-openapi-ui"

更喜欢哪个依赖项？

我正在处理一个 Spring Data MongoDB 项目，该项目通过 Spring Data REST 导出其端点。它使用springdoc-openapispringdoc-openapi-data-rest库的模块为项目中的 Spring Data REST 端点生成OpenAPI接口描述。

我有一个存储库端点，我想从生成的 OpenAPI 文档中排除该端点。

@Repository
public interface ExcludeMeRepository extends
        PagingAndSortingRepository<ExcludeMe, Integer> {}

如果这是通过 包含的 Spring MVC 控制器springdoc-openapi-ui，我可以@Hidden在控制器上使用 Swagger Annotations 库中的注释。然而，这在课堂上似乎不起作用@Repository。

@Hidden // Does not appear to have an effect
@Repository
public interface ExcludeMeRepository extends
        PagingAndSortingRepository<ExcludeMe, Integer> {}

我已经尝试了一些方法，但还没有发现任何可行的方法，而且感觉不像是一种黑客解决方法。

如何从生成的 OpenAPI 文档中排除存储库？

我的 springboot webflux 应用程序正在运行，我能够通过 url 访问 swagger ui：

http://localhost:8080/webjars/swagger-ui/index.html。

注意：对于我来说，Tomcat 使用端口初始化：8080 (http)

POM 包含以下依赖项

      <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.5</version>
        <relativePath/> <!-- lookup parent from repository -->
     </parent>

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>

我的主要java类如下

@OpenAPIDefinition(info = @Info(title = "APIs", version = "1.0", description = "Documentation OHM APIs v1.0"))
public class ReactiveApplication {

  public static void main(String[] args) {
    SpringApplication.run(ReactiveApplication.class, args);
  }

}

突然之间，我无法再在之前工作的同一网址上访问 webflux swagger。

出现以下错误：

2023-01-05 13:49:36,906 WARN  [http-nio-8080-exec-9] o.s.web.servlet.PageNotFound.noHandlerFound: No mapping for GET /webjars/swagger-ui/index.html
2023-01-05 13:49:36,907 …

我正在尝试在 Spring Boot 中使用 Spring实现Open API Doc和Open API UI：

我指的是以下指南：https : //www.baeldung.com/spring-rest-openapi-documentation

maven中的依赖如下：

        <!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-core -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-core</artifactId>
            <version>1.1.49</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.2.20</version>
        </dependency>

我使用的 Spring Boot 版本是 2.2

我在通过以下方式运行应用程序时遇到与元数据相关的错误 ./mvnw spring-boot:run

java.lang.IllegalStateException: Unable to read meta-data for class org.springdoc.core.MultipleOpenApiSupportConfiguration
        at org.springframework.boot.autoconfigure.AutoConfigurationSorter$AutoConfigurationClass.getAnnotationMetadata(AutoConfigurationSorter.java:233) ~[spring-boot-autoconfigure-2.2.2.RELEASE.jar:2.2.2.RELEASE]
        at org.springframework.boot.autoconfigure.AutoConfigurationSorter$AutoConfigurationClass.getOrder(AutoConfigurationSorter.java:204) ~[spring-boot-autoconfigure-2.2.2.RELEASE.jar:2.2.2.RELEASE]
        at org.springframework.boot.autoconfigure.AutoConfigurationSorter$AutoConfigurationClass.access$000(AutoConfigurationSorter.java:150) ~[spring-boot-autoconfigure-2.2.2.RELEASE.jar:2.2.2.RELEASE]
        at org.springframework.boot.autoconfigure.AutoConfigurationSorter.lambda$getInPriorityOrder$0(AutoConfigurationSorter.java:63) ~[spring-boot-autoconfigure-2.2.2.RELEASE.jar:2.2.2.RELEASE]
        at java.base/java.util.TimSort.countRunAndMakeAscending(TimSort.java:360) ~[na:na]
        at java.base/java.util.TimSort.sort(TimSort.java:234) ~[na:na]
        at java.base/java.util.Arrays.sort(Arrays.java:1516) ~[na:na]

任何线索为什么会发生？

我正在使用 SpringDoc 并尝试以编程方式向 OpenApi 添加架构，但没有成功。

    @Bean
public OpenAPI customOpenAPI() {
     Schema mySchema = new Schema<Object>();
     mySchema
     .type("object")
     .$ref("#/components/schemas/MySchema")
     .name("MySchema")
     .addProperties("testStr", new StringSchema());

      return new OpenAPI()
            .servers(servers)
            .info(new Info().title(title).version(version).description(description))
            .components(new Components()
                    .addSchemas("MySchema" , mySchema)
            )
            .tags(tags);
}

mySchema 的描述未添加到我在生成的 YAML 文件中看到的架构列表中，如果我尝试引用它：

apiResponses.entrySet().forEach(response -> response.getValue().addHeaderObject("XxX", 
                  new Header().$ref("#/components/schemas/MySchema")));

swagger UI 中显示以下错误：

paths./XX/v1/test/status/{entry}.get.responses.404.headers.XxX.$ref 处的解析器错误 无法解析引用：无法解析指针：/components/schemas/MySchema

请问您能帮我理解一下吗？

编辑：我正在使用版本1.3.9

如果出现未处理的错误，SpringBoot 应用程序的默认服务器响应是

{
    "timestamp": 1594232435849,
    "path": "/my/path",
    "status": 500,
    "error": "Internal Server Error",
    "message": "this request is failed because of ...",
    "requestId": "ba5058f3-4"
}

我想在应用程序路由的 Springdoc 注释中描述它。

假设有一个标准类DefaultErrorResponse（只是一个模拟名称），它可能如下所示：

@Operation(
  // ... other details
  responses = {
    // ... other possible responses
    @ApiResponse(
      responseCode = "500",
      content = @Content(schema = @Schema(implementation = DefaultErrorResponse.class)))
  }
)

在更糟糕的情况下，这样的类不存在，Spring 仅使用Map底层来创建响应。那么这个注释将更加详细，包括明确提及响应中包含的每个字段。

显然，对于大多数路线来说，这部分@ApiResponse(responseCode="500",...是相同的，并且最好减少重复。

在文档中引入默认错误响应描述的正确方法是什么？

如何从 Swagger UI 禁用或隐藏“服务器”下拉列表？

我的 Maven 依赖项是：

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