标签: springdoc-openui

当我发布时，我会使用HTTPS请求而不是HTTP，但是swagger原始URL仍然是HTTP，我不知道如何设置，并且原始springdoc-openapi-ui配置中没有服务器的文档

https://springdoc.org/index.html#properties

我使用这个库来生成文档：

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

我有这个控制器：

@RestController
public class TestController {

    @GetMapping("/test{hz}")
    public String test(@PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

但我得到这个文档：

为什么required = false不起作用？

我试过这个：

@RestController
public class TestController {

    @GetMapping("/test{hz}")
    public String test(
            @Parameter(description = "foo", required = false)
            @PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

也不起作用

编辑：（@Helen 评论的答案）-我当然知道这一点：

@RestController
public class TestController {

    @GetMapping(value = {"/test", "/test{hz}"})
    public String test(
            @Parameter(description …

我正在使用 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

我正在从 Springfox 3.0 切换到 OpenAPI 3.0 + Springdoc-openapi。
在 Springfox 中，标签顺序是按字母顺序排列的，但在 Springdoc 的 Swagger UI 中，顺序似乎是随机的。

如何控制 UI 上的标签顺序？我更喜欢自己选择的顺序，但也可以按标签名称的字母顺序排序。

@Tag(name = MY_CONTROLLER_TAG_NAME, description = MY_CONTROLLER_TAG_DESC)
public class MyController {

所需订单：

• 分页端点
• 用户访问
• 标记
• 标记 - 管理员
• 用户管理
• 用户管理 - 管理员

实际订单：

• 用户访问
• 标记
• 分页端点
• 标记 - 管理员
• 用户管理 - 管理员
• 用户管理

POM 依赖关系：

        <springdoc-openapi.version>1.6.4</springdoc-openapi.version>
...
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>${springdoc-openapi.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-security</artifactId>
            <version>${springdoc-openapi.version}</version>
        </dependency>

应用程序.yml：

springdoc:
  show-actuator: ${SWAGGER_ENABLED:true}
  swagger-ui:
    doc-expansion: none
  api-docs:
    enabled: ${SWAGGER_ENABLED:true}
  model-converters:
    pageable-converter:
      enabled: true

当库尚未准备好供打算使用 API 的其他微服务使用时，如何在 OpenAPI 3.x 中将 API 标记为未使用

注意：目前，我们构建了很多 API，它们处于不同的开发阶段。有没有办法对此进行注释，以便其他开发人员知道有一些 API 仍在进行中

我将 OpenAPI 与我的项目集成，当我访问 url: 时http://127.0.0.1:11014/swagger-ui/index.html，显示如下错误：

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

 

这是 OpenAPI 配置：

package misc.config.openapi;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * https://springdoc.org/
 * https://github.com/springdoc/springdoc-openapi
 */
@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi …

我正在使用 openapi-generator-maven-plugin 从 springboot 应用程序中的 yaml 文件生成 java 类。我想让所有端点抛出 CustomException。

如何配置插件来做到这一点？

这是 open-ui.yaml。我定义了返回 UserDto 列表的端点“users”。我希望该方法在签名中抛出异常。

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Test Api
  license:
    name: MIT
servers:
  - url: "https://{domain}/test/{basePath}"

paths:
  /users:
    get:
      summary: users
      operationId: getUsers
      tags:
        - users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer

      responses:
        '200':
          description: A page of users
          content:
            application/v1+json; charset=utf-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserDto'
  

pom.xml

     <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>5.3.1</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>
                            ${project.basedir}/swagger/open-ui.yaml
                        </inputSpec>
            .... …

我使用Spring Boot + Spring Data Mongo + Spring REST + Spring HATEOAS来实现 REST 端点。

由于我们传递了超过 5 个查询参数（组织的专有设置，应该不传递），所以我想创建一个 EmployeeDto 类并在 Controller 处传递该类

@GetMapping(value = "/employees", produces = {MediaType.APPLICATION_JSON })
public ResponseEntity<PagedModel<EmployeeModel>> findEmployees(
        EmployeeDto dto,
        @Parameter(hidden=true) String sort,
        @Parameter(hidden=true) String order,
        @Parameter(hidden=true) Pageable pageRequest) {

    // Add needed logic 
    ......
    ......
    ......
    PagedModel<EmployeeModel> model = employeePagedAssembler.toModel(response, employeeAssembler);

    return new ResponseEntity<>(model, HttpStatus.OK);
}

Swagger UI 显示如下 -

{
  "firstName": "string",
  "lastName": "string",
  "age": 0,
  "languageCd": "string",
  "isActive": "string",
  "email": "string",
  "regionCd": …

网络上没有关于如何使用 springdocs-openapi 库 (1.5.7) 获取以下输出的好示例。我希望获得以下输出：

[
  "A", "B", "C"
]

这是基于所提供示例的代码。

@Operation(summary = "")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "OK",
                    content = {@Content(mediaType = "application/json",
                            array = @ArraySchema(schema = @Schema(implementation = String.class)),
                            examples = {@ExampleObject("A"), @ExampleObject("B"), @ExampleObject("C")}
                    )})

这会产生以下输出

[
  "string"
]

上面列出的输出 ["A","B","C"] 如何通过 springdocs-openapi 库实现？

我最近将 swagger UI 从 更改Springfox为SpringDoc OpenApi.

Swagger 在Chrome.

但在Internet Explore我得到以下错误。My IE version is 11

我正在从 springfox 2.9.0 迁移到 springdoc-openapi-ui 1.2.33。我需要根据条件在 swagger ui 上显示或隐藏 PathVariable 。我有两条路径如下

1. 字符串名称标识符 = "{fisrtName}/{lastName}"

2. 字符串名称标识符 = "{fisrtName}"

我根据要求传递上述 nameIdentifier 之一。

我对上述路径使用单个控制器，如下所示

@GetMapping(path = "persons/${nameIdentifier}/display")
public List<Person> getPersons(@PathVariable String fisrtName,
    @IgnoreLastName @PathVariable Optional<String> lastName) {

}

在 springfox 中，我能够使用docket.ignoredParameterTypes(IgnoreLastName.class)如下所示的方法来实现它。

@Bean
public Docket api() {

    Docket docket;

    docket = new Docket(DocumentationType.SWAGGER_2).select()                
     .apis(RequestHandlerSelectors.basePackage("go.controller")).paths(PathSelectors.any()).build()
                .apiInfo(apiInfo());

        if (!nameIdentifier.contains("lastName")) {
            docket.ignoredParameterTypes(IgnoreLastName.class);
        }
        return docket;
    }

但在 springdoc open api 中我无法实现相同的目标。同样感谢您的帮助。编码是用java完成的

谢谢

我正在使用 Spring Boot 和 Open API 3。当我发出 POST 请求时，通过 OAS2 Swagger，我看到所有字符串字段都以 Spring 的默认值出现，并且我没有看到通过 SpringDoc Open UI 删除它的方法也不通过代码。

{
  "firstName": "string",
  "lastName": "string",
  "age": 0,
  "email": "string",
  "address1": "string",
  "address2": "string",
  "address3": "string",
  "telephone" : "0",
  "department" : "string",
  .....
}

这里消费者不愿意在发出请求时从字段中删除字符串。有什么办法吗

1. 如果我们可以删除“string”作为值并将 null 或“”设置为默认值？
2. 如果我们可以读取自定义对象并将找到“字符串”的所有值重置为 null，有什么办法吗？