springdoc-openapi: Как добавить пример POST-запроса?

Question

Есть следующий метод контроллера:

    @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-api v1.4.3.

Answer 1

Вы можете использовать аннотацию @ExampleObject.

Обратите внимание, что вы также можете в примерах использовать ref @ExampleObject(ref="..."), если хотите сослаться на существующий образец объекта. Или, в идеале, получите примеры из внешнего файла конфигурации и добавьте их с помощью OpenApiCustomiser, как это сделано в этом тесте:

• https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app90/SpringDocTestApp.java

Вот пример кода с использованием @ExampleObject:

@PostMapping("/test/{id}")
public void testme(@PathVariable("id") String id, @RequestBody(content = @Content(examples = {
        @ExampleObject(
                name = "Person sample",
                summary = "person example",
                value =
                        "{\"email\": [e-mail],"
                                + "\"firstName\": \"josh\","
                                + "\"lastName\": \"spring...\""
                                + "}")
})) PersonDTO personDTO) { }

Answer 2

@ExampleObject можно использовать для @RequestBody и @ApiResponse для добавления примеров для springdoc openapi: https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-javadoc/src/test/java/test/org/springdoc/api/app90/HelloController.java

      @RestController
public class HelloController {

    /**
     * Test 1.
     *
     * @param hello the hello
     */
    @GetMapping("/test")
    @ApiResponses(value = { @ApiResponse(description = "successful operation",content = { @Content(examples = @ExampleObject(name = "500", ref = "#/components/examples/http500Example"), mediaType = "application/json", schema = @Schema(implementation = User.class)), @Content(mediaType = "application/xml", schema = @Schema(implementation = User.class)) }) })
    public void test1(String hello) {
    }

    /**
     * Test 2.
     *
     * @param hello the hello
     */
    @PostMapping("/test2")
    @RequestBody(
            description = "Details of the Item to be created",
            required = true,
            content = @Content(
                    schema = @Schema(implementation = User.class),
                    mediaType = MediaType.APPLICATION_JSON_VALUE,
                    examples = {
                            @ExampleObject(
                                    name = "An example request with the minimum required fields to create.",
                                    value = "min",
                                    summary = "Minimal request"),
                            @ExampleObject(
                                    name = "An example request with all fields provided with example values.",
                                    value = "full",
                                    summary = "Full request") }))
    public void test2(String hello) {
    }

}

если вы хотите добавить OpenApiCustomiser для загрузки ваших примеров из ресурсов, вам нужно будет начать с чего-то вроде этого: https://github.com/springdoc/springdoc-openapi/blob/master/springdoc-openapi-javadoc/src/ тест/java/тест/org/springdoc/api/app90/SpringDocTestApp.java

      @Bean
    public OpenApiCustomiser openApiCustomiser(Collection<Entry<String, Example>> examples) {
        return openAPI -> {
            examples.forEach(example -> {
                openAPI.getComponents().addExamples(example.getKey(), example.getValue());
            });
        };
    }

Для параметров заголовка, файла cookie, запроса или пути вы можете использовать @Parameter: https://docs.swagger.io/swagger-core/v2.0.0-RC3/apidocs/io/swagger/v3/oas/annotations/Parameter.html .

с перечислением ParameterIn: https://docs.swagger.io/swagger-core/v2.0.0/apidocs/io/swagger/v3/oas/annotations/enums/ParameterIn.html

например

      @Parameter(in = ParameterIn.PATH, name = "id", description="Id of the entity to be update. Cannot be empty.",
        required=true, examples = {@ExampleObject(name = "id value example", value = "6317260b825729661f71eaec")})

Другой способ — добавить @Schema(type = "string", example = "min") в ваш DTO. например: https://www.dariawan.com/tutorials/spring/documenting-spring-boot-rest-api-springdoc-openapi-3/

Answer 3

Если кому-то все еще интересно, вот как можно программно добавить примеры в конкретную конечную точку:

      @Bean
 public OpenApiCustomiser mockExamples() {
    return openAPI ->
        getRequestBodyContent(openAPI, PXL_MOCK_PATH + "/transactions", "application/json").ifPresent(request ->
            Arrays.stream(PxlMockCase.values()).forEach(mockCase -> {
                request.addExamples(
                    mockCase.name(),
                    new Example()
                        .description(mockCase.getDescription())
                        .value(TransactionCodeRequest.builder().accountId(mockCase.getAccountId()).workflowId(15).build())
                );
            }));
}

private Optional<MediaType> getRequestBodyContent(OpenAPI api, String path, String bodyType) {
    return Optional.ofNullable(api.getPaths())
        .map(paths -> paths.get(path))
        .map(PathItem::getPost)
        .map(Operation::getRequestBody)
        .map(RequestBody::getContent)
        .map(content -> content.get(bodyType));
}

Answer 4

If we are using spring boot:
Add it to our Maven project, we need a dependency in the pom.xml file.
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

@Configuration
@EnableSwagger2
public class SpringConfig {                                    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                           
    }
}

**Configuration Without Spring Boot**

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
      .addResourceLocations("classpath:/META-INF/resources/");
 
    registry.addResourceHandler("/webjars/**")
      .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

**Verify:**
verify that Springfox is working, you can visit the following URL in your browser:
http://localhost:8080/our-app-root/api/v2/api-docs

To use Swagger UI, one additional Maven dependency is required:
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

you can test it in your browser by visiting http://localhost:8080/our-app-root/swagger-ui.html