How to specify server url and description in OpenAPI when using Quarkus?

Question

I am trying to get the following output in my /openApi URL of my Quarkus Rest service.

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

I can get the result using the @OpenAPIDefinition tag in my actual class, but I already have a bunch of OpenAPI-specific things defined in my application.properties file ( mp.openapi.extensions.smallrye.info.title , mp.openapi.extensions.smallrye.info.version , etc.)

I can get a list of servers by specifying the following property:

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

That property returns the following in my /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

I'm just trying to figure out how to also add the description tags for the various servers.

I have seen there is also a property called quarkus.smallrye-openapi.servers but that also just specifies a list of servers.

Answer 1

Another solution could be to declare the servers and their description in a static OpenAPI schema file. Eg you can create under META-INF/openapi.yaml an OpenAPI schema file with the servers information:

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

More information can be found in the quarkus doc: https://quarkus.io/guides/openapi-swaggerui#loading-openapi-schema-from-static-files

Answer 2

Just in case anybody has similar problem.

I can now get my Quarkus service to generate an openApi contract that I can import into Stoplight with no errors.

In the actual java class I have a bunch of tags as follows:

@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) {

And I then have a openapi.yml file in under my resources folder in a META-INF subdirectory as follows:

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: []

Then just to complete the setup I have a bunch of settings in my application.properties file as follows:

##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

its quite mashup of various settings, but it seems to work.