Início / coding / Perguntas / 79275521
Accepted
nik0x1
Asked: 2024-12-12 22:42:20 +0800 CST

Resumo e descrição do objeto Path Item do OpenAPI

  • 772

Estou desenvolvendo REST API usando quarkus-restimplementação do Jakarta REST (anteriormente conhecido como JAX-RS). Também uso quarkus-smallrye-openapiextensão para gerar minha especificação de API (OpenAPI v3).

Como posso preencher os campos: resumo e descrição de um objeto Path Item usando anotações ou de outra forma (sem escrita manual de especificações)?

java

2 respostas

  1. Best Answer

    Não há realmente uma maneira de fazer isso usando as anotações padrão. Você tem algumas opções envolvendo o arquivo OpenAPI estático ou implementando um OASFilterpara adicionar o resumo e/ou descrição.

    OpenAPI estático

    Colocando um openapi.yamlou openapi.jsonem META-INF(dentro src/main/resourcesde projetos Maven), você pode definir apenas o pathse suas descrições que lhe interessam. Este arquivo será mesclado com o resultado da varredura de anotação.

    paths:
  "/foo":
    summary: "...",
    description: "..."
  "/foo/{bar}":
    summary: "...",
    description: "..."

    OASFilterImplementação

    Escreva uma implementação de org.eclipse.microprofile.openapi.OASFiltere configure-a definindo o nome da classe totalmente qualificado como o valor de property mp.openapi.filter. Você pode substituir method filterPathItemcom qualquer lógica que desejar para definir as propriedades. Por exemplo, você pode procurá-las em config properties obtendo primeiro um Configde ConfigProvider.

    class MyFilter implements OASFilter {
    @Override
    public PathItem filterPathItem(PathItem pathItem) {
        // Logic to set the summary or description on pathItem goes here.
        return pathItem;
    }
}
    • 2

  2. Você pode fazer algo assim com anotações:

    @GET
@Path("options/{foo}")
public Response getFoo(
   @Schema(description = "some desc.",required = true)
   @PathParam("foo") String foo
) {
....

    ou você pode mesclar/estender/enriquecer a especificação openapi gerada colocando um openapi.yaml em resources/META-INF.

    Nos itens do caminho, faça isto:

    @GET
@Path("search")
@Operation(operationId = "SearchFoo", summary = "Search Foos", description = "Search Foos by status and date")
   public Foo searchFoo...
    • -1

relate perguntas