MicroProfile OpenAPI Specification

@GET
@Path("/findByStatus")
@Operation(summary = "Finds Pets by status",
           description = "Multiple status values can be provided with comma separated strings")
public Response findPetsByStatus(...) { ... }

/pet/findByStatus:
  get:
    summary: Finds Pets by status
    description: Multiple status values can be provided with comma separated strings
    operationId: findPetsByStatus

@GET
@Path("/{username}")
@Operation(summary = "Get user by user name")
@APIResponse(description = "The user",
             content = @Content(mediaType = "application/json",
                                schema = @Schema(implementation = User.class))),
@APIResponse(responseCode = "400", description = "User not found")
public Response getUserByName(
        @Parameter(description = "The name that needs to be fetched. Use user1 for testing. ", required = true) @PathParam("username") String username)
 {...}

/user/{username}:
    get:
      summary: Get user by user name
      operationId: getUserByName
      parameters:
      - name: username
        in: path
        description: 'The name that needs to be fetched. Use user1 for testing. '
        required: true
        schema:
          type: string
      responses:
        default:
          description: The user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        400:
          description: User not found

@POST
@Path("/user")
@Operation(summary = "Create user",
           description = "This can only be done by the logged in user.")
public Response methodWithRequestBody(
          @RequestBody(description = "Created user object", required = true,
                       content = @Content(schema = @Schema(implementation = User.class))) User user,
          @QueryParam("name") String name, @QueryParam("code") String code)
          { ... }

post:
    summary: Create user
      description: This can only be done by the logged in user.
      operationId: methodWithRequestBody
    parameters:
    - name: name
      in: query
      schema:
      type: string
    - name: code
      in: query
      schema:
      type: string
    requestBody:
      description: Created user object
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/User'
            required: true
    responses:
      default:
        description: no description

@OpenAPIDefinition(
    servers = {
        @Server(
            description = "definition server 1",
            url = "http://{var1}.definition1/{var2}",
            variables = {
                @ServerVariable(name = "var1",
                                description = "var 1",
                                defaultValue = "1",
                                enumeration = {"1", "2"}),
                @ServerVariable(name = "var2",
                                description = "var 2",
                                defaultValue = "1",
                                enumeration = {"1", "2"})})})
@Server(
    description = "class server 1",
    url = "http://{var1}.class1/{var2}",
    variables = {
            @ServerVariable(
                      name = "var1",
                      description = "var 1",
                      defaultValue = "1",
                      enumeration = {"1", "2"}),
            @ServerVariable(
                      name = "var2",
                      description = "var 2",
                      defaultValue = "1",
                      enumeration = {"1", "2"})})
@Server(
    description = "class server 2",
    url = "http://{var1}.class2",
    variables = {
            @ServerVariable(
                       name = "var1",
                       description = "var 1",
                       defaultValue = "1",
                       enumeration = {"1", "2"})})
public class ServersResource {

    @GET
    @Path("/")
    @Server(
        description = "method server 1",
        url = "http://{var1}.method1",
        variables = {
            @ServerVariable(
                      name = "var1",
                      description = "var 1",
                      defaultValue = "1",
                      enumeration = {"1", "2"})})
    @Server(
        description = "method server 2",
        url = "http://method2"
    )
    public Response getServers() {
        return Response.ok().entity("ok").build();
    }
}

openapi: 3.0.2
servers:
- url: http://{var1}.definition1/{var2}
  description: definition server 1
  variables:
    var1:
      description: var 1
      enum:
      - "1"
      - "2"
      default: "1"
    var2:
      description: var 2
      enum:
      - "1"
      - "2"
      default: "1"
paths:
  /:
    get:
      operationId: getServers
      responses:
        default:
          description: default response
      servers:
      - url: http://{var1}.class1/{var2}
        description: class server 1
        variables:
          var1:
            description: var 1
            enum:
            - "1"
            - "2"
            default: "1"
          var2:
            description: var 2
            enum:
            - "1"
            - "2"
            default: "1"
      - url: http://{var1}.class2
        description: class server 2
        variables:
          var1:
            description: var 1
            enum:
            - "1"
            - "2"
            default: "1"
      - url: http://{var1}.method1
        description: method server 1
        variables:
          var1:
            description: var 1
            enum:
            - "1"
            - "2"
            default: "1"
      - url: http://method2
        description: method server 2
        variables: {}

@Schema(name="MyBooking", description="POJO that represents a booking.")
public class Booking {
    @Schema(required = true, example = "32126319")
    private String airMiles;

    @Schema(required = true, example = "window")
    private String seatPreference;
}

components:
  schemas:
    MyBooking:
      description: POJO that represents a booking.
      required:
      - airMiles
      - seatPreference
      type: object
      properties:
        airMiles:
          type: string
          example: "32126319"
        seatPreference:
          type: string
          example: window

@POST
public Response createBooking(
     @RequestBody(description = "Create a new booking.",
                  content = @Content(mediaType = "application/json",
                                     schema = @Schema(implementation = Booking.class))) Booking booking) {

post:
  operationId: createBooking
  requestBody:
    description: Create a new booking.
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/MyBooking'