标签: springdoc

我使用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": …

对于某些错误代码，我正在尝试向 API 中的所有端点添加默认错误模型。

我通过阅读以下问题找到了部分解决方案：

• Springfox -> Springdoc：如何公开其他模型
• https://github.com/springdoc/springdoc-openapi/issues/381

这是我为该定制创建的 bean：

    @Bean
    public OpenApiCustomiser customOpenApiCustomiser() {
        return openApi -> {
            openApi.getPaths().values().forEach(pathItem -> pathItem.readOperations().forEach(operation -> {

                Schema sharedErrorSchema = ModelConverters.getInstance()
                        .read(Error.class)
                        .getOrDefault("Error", new Schema());

                MediaType sharedMediaType = new MediaType().schema(sharedErrorSchema);
                Content sharedContent = new Content()
                        .addMediaType(APPLICATION_JSON_VALUE, sharedMediaType);

                ApiResponses apiResponses = operation.getResponses();

                ApiResponse response = new ApiResponse()
                        .description("Unhandled server error")
                        .content(sharedContent);
                apiResponses.addApiResponse("500", response);
            }));
        };
    }

我的 Error 类看起来像：

public class Error {
    private String message;
    private List<ErrorItem> errorItems;
}

问题是，当我在 swagger-ui 中打开端点定义之一时，出现以下错误：

Could …

我正在使用 swagger 和 springdoc-openapi-ui-1.4.3

@SecurityRequirement(name = "security_auth")
public class ProductController {}

设置安全架构

@SecurityScheme(name = "security_auth", type = SecuritySchemeType.OAUTH2,
        flows = @OAuthFlows(authorizationCode = @OAuthFlow(
                authorizationUrl = "${springdoc.oAuthFlow.authorizationUrl}"
                , tokenUrl = "${springdoc.oAuthFlow.tokenUrl}",scopes = {
                @OAuthScope(name = "IdentityPortal.API", description = "IdentityPortal.API")})))
public class OpenApiConfig {}

安全配置

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {// @formatter:off
        http
                .authorizeRequests()
                .antMatchers("/v3/api-docs/**", "/swagger-ui/**", "/swagger-ui.html")
                .permitAll()
                .antMatchers(HttpMethod.GET, "/user/info", "/api/foos/**")
                .hasAuthority("SCOPE_read")
                .antMatchers(HttpMethod.POST, "/api/foos")
                .hasAuthority("SCOPE_write")
                .anyRequest()
                .authenticated()
                .and()
                .oauth2ResourceServer()
                .jwt();
    }
}

有依赖关系 …

我有一个 spring（启动）服务器，想要使用 springdoc 从注释生成 OpenAPI 规范。

我有一个请求，请求正文中有两个参数。我希望第一个是必需的，第二个是可选的。

@RequestBody(required = {true|false})似乎只将主体中的所有参数设置为（不需要）。@Parameter另一方面，Javadoc说要使用io.swagger.v3.oas.annotations.parameters.RequestBody

这是我的代码，我希望生成一个规范，其中第一个参数是必需的，第二个参数是可选的：

@GetMapping("/fstVector")
public ResponseEntity<Vector> fstV(@RequestBody final Vector v1, @RequestBody(required = false) final Vector v2) {
    return new ResponseEntity<>(v1, HttpStatus.OK);
}

@PostMapping("/fstVector")
public ResponseEntity<Vector> fstVPost(@RequestBody(required = true) final Vector v1, @RequestBody(required = false) final Vector v2) {
    return new ResponseEntity<>(v1, HttpStatus.OK);
}

然而，生成的规范需要两个参数：

  /pond/fstVector:
    get:
      tags:
      - circle-escape-controller
      operationId: fstV
      parameters:
      - name: v1
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/Vector'
      - name: v2
        in: query
        required: …

网络上没有关于如何使用 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 版本 2.1.9 从 Springfox 迁移到 Springdoc。

因此，必须重写注释，并且我找不到旧 Swagger 注释的等效注释。

我有这个 API 控制器：

@GetMapping
@ApiOperation(value = "Load Building")
@ApiResponses(value = {
   @ApiResponse(code = 200, message = "OK", response = Building.class, responseContainer = "Page")
})
public ResponseEntity<Page<Building>> getBuilding(Pageable building) {
   final Page<Building> building = buildingrepo.findAll(page).map(bw -> mapper.map(bd, Building.class));

return ResponseEntity.ok().body(building);

使用新的 Swagger 注释，必须重新编写它，但我不知道如何将“Building.class”放入响应架构中的可分页中。我不能再使用“responseContainer”

@GetMapping
@Operation(summary = "Load Building")
@ApiResponses(value = {
   @ApiResponse(responseCode = "200", 
                description = "OK",
                content = @Content(schema = @Schema(implementation = Building.class))) // <--- Here i need the …

我正在尝试使用以下代码将 springfox 迁移到 springdoc：

import io.swagger.annotations.ApiModelProperty;

@ApiModelProperty(position = 30, required = true, value = "Group value")

到

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(position = 20, required = false)

但我找不到position和value。你知道在 springdoc 中替换它们的正确方法是什么吗？

我有一个准系统的 SpringBoot 项目，pom 文件中包含最新的 Springdoc 依赖项（截至撰写本文时）：

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

另外我只有网络启动器依赖项：

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

它与 Spring Boot 2.7.5 配合良好。在本地计算机上，我可以访问http://localhost:8080/swagger-ui.html并http://localhost:8080/v3/api-docs重定向到 OpenAPI 资源。但是，一旦我将 Spring Boot 版本更改为 3.0.0 并重新启动应用程序，我只能获得404 NOT FOUND上述两个资源。

有没有人找到一种方法可以使 Spring Boot 3.0.0 工作？

我升级到 Spring boot 3.0.7 并尝试让我的 Open API (swagger) 再次工作，具有这些依赖项（根据springdoc）：

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

  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
  </dependency>

...但是当我构建我的应用程序时，出现以下错误：

java.lang.IllegalStateException: Failed to introspect Class [org.springdoc.webmvc.api.OpenApiWebMvcResource] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@1de0aca6]

...“原因”为：

java.lang.NoClassDefFoundError: javax/servlet/http/HttpServletRequest

当我查看罐子OpenApiWebMvcResource中的内容时，它确实是从而不是org.springdoc:springdoc-openapi-webmvc-core:1.7.0导入的：javaxjakarta

package org.springdoc.webmvc.api;
    
import com.fasterxml.jackson.core.JsonProcessingException;
import io.swagger.v3.oas.annotations.Operation;
import java.util.Locale;
import java.util.Optional;
import javax.servlet.http.HttpServletRequest;
...

那么这是一个问题openapi-webmvc-core，还是我接线有问题？

有以下Controller方法：

    @ApiResponses(value = {@ApiResponse(responseCode = "200")})
    @GetMapping(value = API_URI_PREFIX + PRODUCTS_URI, produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseStatus(HttpStatus.OK)
    public Flux<Product> getProducts(@Valid @NotNull PagingAndSorting pagingAndSorting) {
   }

我需要找到一种如何在对象Swagger示例中显示的方法PagingAndSorting。

我正在使用springdoc-apiv1.4.3。