使用 Quarkus 时如何在 OpenAPI 中指定服务器 url 和描述？

Question

我试图在我的 Quarkus Rest 服务的/openApi URL 中获得以下输出。

servers:
  - url: 'https://serviceproxy.sun.ac.za/sunstudent-api'
    description: The production environment base
  - url: 'https://serviceproxy-test.sun.ac.za/sunstudent-api'
    description: The test environment base url
  - url: 'https://serviceproxy-dev.sun.ac.za/sunstudent-api'
    description: The development environment base url

我可以在我的实际课程中使用@OpenAPIDefinition标记获得结果，但是我已经在我的application.properties文件（ mp.openapi.extensions.smallrye.info.title 、 mp.openapi.extensions.smallrye.info.version等）

我可以通过指定以下属性来获取服务器列表：

mp.openapi.servers=https://serviceproxy-dev.sun.ac.za/sunstudent-api,https://serviceproxy-test.sun.ac.za/sunstudent-api,https://serviceproxy.sun.ac.za/sunstudent-api

该属性在我的/openApi中返回以下内容：

servers:
- url: https://serviceproxy-test.sun.ac.za/sunstudent-api
- url: https://serviceproxy-dev.sun.ac.za/sunstudent-api
- url: https://serviceproxy.sun.ac.za/sunstudent-api

我只是想弄清楚如何为各种服务器添加description标签。

我已经看到还有一个名为quarkus.smallrye-openapi.servers的属性，但它也只是指定了一个服务器列表。

Answer 1

另一种解决方案可能是在静态 OpenAPI 模式文件中声明服务器及其描述。 例如，您可以在META-INF/openapi.yaml下创建一个带有服务器信息的 OpenAPI 模式文件：

openapi: 3.0.3
servers:
- url: https://serviceproxy.sun.ac.za/sunstudent-api
  description: The production environment base
- url: https://serviceproxy-test.sun.ac.za/sunstudent-api
  description: The test environment base url
- url: https://serviceproxy-dev.sun.ac.za/sunstudent-api
  description: The development environment base url

更多信息可以在 quarkus 文档中找到： https ://quarkus.io/guides/openapi-swaggerui#loading-openapi-schema-from-static-files

Answer 2

以防万一有人有类似的问题。

我现在可以让我的 Quarkus 服务生成一个 openApi 合约，我可以将它导入到 Stoplight 中而不会出现错误。

在实际的java类中，我有一堆标签如下：

@GET
  @Path("/studentprofile")
  @Produces(MediaType.APPLICATION_JSON)
  @Operation(summary = "Get student profile for parking application", description="Get student profile for parking application")
  @APIResponse(responseCode = "200", description = "The student profile for parking application",
               content = @Content(mediaType = "application/json",
                                  schema = @Schema(implementation = GetStudParkingProfile_Response.class)))
  @APIResponse(responseCode = "400", description = "Invalid parameters",
               content = @Content(mediaType = "application/json",
                                  schema = @Schema(implementation = ErrorResponse.class)))
  @APIResponse(responseCode = "500", description = "Internal Server error",
               content = @Content(mediaType = "application/json",
                                  schema = @Schema(implementation = ErrorResponse.class)))
  public Response getStudentParkingProfile(@Parameter(description = "SU Number of student", required = true)@QueryParam("suNumber") String suNumber,
                                           @Parameter(description = "year of study that profile is required for", required = true)@QueryParam("year") int year) {

然后我在 META-INF 子目录中的资源文件夹下有一个 openapi.yml 文件，如下所示：

openapi: 3.0.3
servers:
- url: https://serviceproxy.sun.ac.za/sunstudent-api
  description: The production environment base
- url: https://serviceproxy-test.sun.ac.za/sunstudent-api
  description: The test environment base url
- url: https://serviceproxy-dev.sun.ac.za/sunstudent-api
  description: The development environment base url
tags: ##Tags must be in alphabetical order....
  - name: MicroProfile Health
    description: Check the health of the application
  - name: Parking Service
    description: Retrieve info on students for use with parking application    
security:
  - BasicAuth: []

然后只是为了完成设置，我的 application.properties 文件中有一堆设置，如下所示：

##openapi headers
mp.openapi.extensions.smallrye.info.title=Student information for parking application
mp.openapi.extensions.smallrye.info.version=1.0.0
mp.openapi.extensions.smallrye.info.description=API for retrieving student specific information for parking application
mp.openapi.extensions.smallrye.info.contact.email=elmarm@sun.ac.za
mp.openapi.extensions.smallrye.info.contact.name=Elmar Matthee
mp.openapi.extensions.smallrye.info.contact.url=http://www.sun.ac.za
quarkus.smallrye-openapi.info-license-name=SU Contract
quarkus.smallrye-openapi.info-license-url=http://www.sun.ac.za
quarkus.smallrye-openapi.security-scheme-name=BasicAuth
quarkus.smallrye-openapi.security-scheme-description=Basic http auth
quarkus.smallrye-openapi.security-scheme=basic
mp.openapi.extensions.smallrye.operationIdStrategy=METHOD

它是各种设置的混搭，但它似乎有效。