我已经使用 Java 项目的 pom 文件中的以下工件安装了 swagger-ui：

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

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-security</artifactId>
      <version>1.5.2</version>
   </dependency>

当我访问此 URL 时，我可以查看 RESTful 端点的 swagger ui

http://localhost:8081/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config

但不是这个链接

http://localhost:8081/swagger-ui/index.html

为什么是这样？如何将其改回预期的 URL？

如何在 Spring Security 保护的 Spring Boot 应用程序中允许匿名访问springdoc-openapi-ui (OpenAPI 3.0 /swagger-ui.html)？

我正在使用Spring Boot REST OpenAPI 3规范。在此示例中，我希望Custom-Header-Version=v1在向每个端点发出请求时全局设置我想要传递的标头 ( )。

现在的问题是，我有100 个 REST 端点，对于每个端点，我需要不断添加@Parameter(in = ParameterIn.HEADER .....此配置，而不是我希望在全局范围内设置它。如果我们在OpenAPI中可以做到这一点，有什么办法吗？

有什么方法可以从 Spring doc ui 中删除 SmartBear 徽标吗？

@RestController
@RequestMapping("/api")
@Tag(name = "contact", description = "the Contact API")
public class HelloController {

    @Operation(summary = "Find Contacts by name", description = "Name search by %name% format", tags = {"contact"})
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "successful operation", content = @Content(array = @ArraySchema(schema = @Schema(implementation = PersonDTO.class))))})
    @Parameter(in = …

我正在使用最新版本的 springdoc-openapi (1.3.0)。现在我想按“名称”属性对用户界面中的标签进行排序。

我了解“springdoc.swagger-ui.tagsSorter”配置，并且我可以使用自定义排序器功能。但我找不到该函数应该是什么样子的示例。

我尝试了以下似乎不起作用的方法：

springdoc.swagger-ui.tagsSorter=(a, b) => a.get("name").localeCompare(b.get("name"))

用于GroupedOpenApi定义 API 组时，添加到每个端点的通用参数集不存在于参数列表中。下面是各自的代码

@Bean
public GroupedOpenApi v1Apis() {
    return GroupedOpenApi.builder().group("v1 APIs")
            // hide all v2 APIs
            .pathsToExclude("/api/v2/**", "/v2/**")
            // show all v1 APIs
            .pathsToMatch("/api/v1/**", "/v1/**")
            .build();
}

以及将标准标头添加到所有端点的类

@Component
public class GlobalHeaderAdder implements OperationCustomizer {
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        operation.addParametersItem(new Parameter().$ref("#/components/parameters/ClientID"));
        operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
        List<Parameter> parameterList = operation.getParameters();
        if (parameterList!=null && !parameterList.isEmpty()) {
            Collections.rotate(parameterList, 1);
        }
        return operation;
    }
}

实际产量

预期输出

解决方法

添加要在应用程序属性文件中包含/排除的路径可以解决该错误。但代码级别的一些东西将非常感激。

下面是与我的情况类似的代码

@ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "OK", content = {@Content(schema = @Schema(
                implementation =  // <-- What to specify here?
            ))})
})
@GetMapping(value = "/user")
public ResponseEntity<List<User>> getUsers() {
    return ResponseEntity.ok().body(Arrays.asList(new User(), new User()));
}

如何指定从端点返回的用户列表ApiResponse()？

请注意，Open-API-Definition 不是项目的一部分，而是在另一个项目中指定的。

使用 Spring Boot 2.4.5 和 IntelliJ 2021.2。迁移后

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

到

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

每次我访问http://localhost:8080/swagger-ui.html. 该页面说：

获取错误未定义/v3/api-docs

当我检查日志时：

java.lang.IllegalStateException：为“/v3/api-docs”映射的处理程序方法不明确：{public org.springframework.http.ResponseEntity springfox.documentation.oas.web.OpenApiControllerWebMvc.getDocumentation(java.lang.String,javax.servlet) .http.HttpServletRequest), public java.lang.String org.springdoc.webmvc.api.OpenApiWebMvcResource.openapiJson(javax.servlet.http.HttpServletRequest,java.lang.String) 抛出 com.fasterxml.jackson.core.JsonProcessingException} org.springframework.web.servlet.handler.AbstractHandlerMethodMapping.lookupHandlerMethod（AbstractHandlerMethodMapping.java:426）在org.springframework.web.servlet.handler.AbstractHandlerMethodMapping.getHandlerInternal（AbstractHandlerMethodMapping.java:377）在org.springframework.web.servlet。 mvc.method.RequestMappingInfoHandlerMapping.getHandlerInternal（RequestMappingInfoHandlerMapping.java:125）在org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping.getHandlerInternal（RequestMappingInfoHandlerMapping.java:67）在org.springframework.web.servlet.handler.AbstractHandlerMapping。 getHandler(AbstractHandlerMapping.java:498) 在 org.springframework.web.servlet.DispatcherServlet.getHandler(DispatcherServlet.java:1257) 在 org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1039) 在 org.springframework .web.servlet.DispatcherServlet.doService(DispatcherServlet.java:963) 在 org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006) 在 org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java :898)

似乎有一个重复的处理程序方法，与 SpringFox 具有相同的路径，我如何从 SpringFox 中删除该方法（它不再存在于我的 pom 文件中）？

我想知道 Swagger 中是否有一个选项可以授权对包含外部文档的 url 的请求。

我有以下配置，我感兴趣的是urls[1]部分

springdoc.swagger-ui.urls[0].url=/v3/api-docs
springdoc.swagger-ui.urls[0].name=default
springdoc.swagger-ui.urls[1].url=https://asdasd.blob.core.windows.net/my-api/docs.spec
springdoc.swagger-ui.urls[1].name=additional

我可以从服务器（直接从机器上curl）访问文档，但是从Swagger（因此浏览器）我不能。我想知道是否有一个选项可以添加例如。Authorization Bearer xxxx对此请求或实际上使服务器发出请求，而不是客户端。

为了澄清 -我想从远程服务器获取带有 OpenAPI 定义的第二个文件，所以我正在谈论这个：

不是Authorize部分

我实施的解决方案：

海伦指出的可行 - 拦截请求并添加标头 - 但不幸的是，在我的情况下，还存在与存储的防火墙设置有关的问题。只有来自服务器的流量，而不是客户端（浏览器）通过，所以我：

1. 将 url 设置为我的域中的某个内容
   springdoc.swagger-ui.urls[1].url=v3/api-docs/additional
2. 为远程主机的 url 指定另一个属性
   mydomain.swagger-ui.additionalDocsUrl=...
3. 实现了一个处理该 url 的自定义控制器 - 它作为服务器而不是客户端从远程获取 json，以便防火墙传递该请求
   

@Hidden
@RestController
@RequestMapping("/v3/api-docs/additional")
@RequiredArgsConstructor
public class AdditionalOpenApiController {

    @Value("${mydomain.swagger-ui.additionalDocsUrl}")
    private String additionalDocsUrl;

    @Cacheable(value = "ADDITIONAL_API_DOCS", unless = "#result != null")
    @GetMapping(produces = "application/json")
    public String getAdditionalDocs() {
        // in my case remote produces application/octet-stream …

我正在使用 springdoc 生成我的 OpenAPI 文档。

public class MyDto {
    ....
    @JsonFormat(shape = JsonFormat.Shape.STRING)
    private Duration duration;
    ....
}

OpenApi 显示的定义MyDto如下，持续时间被反序列化为类似以下内容：

"duration": {
    "seconds": 0,
    "nano": 0,
    "negative": true,
    "zero": true,
    "units": [
      {
        "dateBased": true,
        "timeBased": true,
        "duration": {
          "seconds": 0,
          "nano": 0,
          "negative": true,
          "zero": true
        },
        "durationEstimated": true
      }
    ]
  }

我希望将其格式化为字符串，而不必添加@Schema(type = "string", format = "duration")到每个字段java.util.Duration的所有 DTO 中Duration。

我jackson-datatype-jsr310的类路径和序列化/反序列化负载按预期使用ISO 8601格式的字符串工作，除了 OpenAPI 显示错误的格式。

是否有可能以某种方式告诉 OpenAPIjava.util.Duration …

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 …