swagger-core

swagger-core copied to clipboard

I'm having a hard time to generate a correct Openapi documentation using swagger-maven-plugin-jakarta.

I've created a simple springboot application just to clarify:

Environment:

swagger-maven-plugin-jakarta: 2.2.28
swagger-core-jakarta: 2.2.28
swagger-annotations: 2.2.28

I have a simple API:

package com.example.demo.controller;

import static jakarta.ws.rs.core.Response.Status.CREATED;

import com.example.demo.controller.dto.RequestDto;
import com.example.demo.controller.dto.ResponseDto;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotNull;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/v1/auth")
@Tag(name = "Simple API", description = "Operations related to a simple API")
public class SimpleController {

  @POST
  @Path("/create")
  @Operation(summary = "Create",
      description = "Create a simple entity",
      responses = {
          @ApiResponse(responseCode = "201",
              description = "Entity created",
              content = @Content(
                  mediaType = MediaType.APPLICATION_JSON,
                  schema = @Schema(implementation = ResponseDto.class))),
          @ApiResponse(responseCode = "500", description = "Internal server error")
      })
  public Response create(@NotNull @Valid final RequestDto dto) {

    try {
      final var responseDto = new ResponseDto();
      return Response.status(CREATED)
          .entity(responseDto)
          .build();
    } catch (Exception e) {
      return Response.serverError().build();
    }
  }

}

Then I have two simple dtos:

package com.example.demo.controller.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
import jakarta.validation.constraints.NotBlank;

@Schema(name = "Request")
public class RequestDto {

  @Schema(minLength = 1, maxLength = 10, requiredMode = RequiredMode.REQUIRED,
      name = "id", description = "Id of entity to be created", example = "34786293")
  @NotBlank(message = "Id cannot be blank")
  private String id;
}```

```java
package com.example.demo.controller.dto;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode;
import java.time.ZonedDateTime;

@Schema(name = "Response")
public class ResponseDto {

  @Schema(minLength = 1, maxLength = 10, requiredMode = RequiredMode.REQUIRED,
      name = "id", description = "Id of entity to be created", example = "34786293")
  private String id;

  @Schema(format = "date-time", requiredMode = RequiredMode.REQUIRED,
      description = "Date in ISO 8601 format of YYYY-MM-DDThh:mm:ss.SSSZ in UTC",
      name = "created_at", example = "2021-05-26T15:36:19.000Z")
  @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss.SSSX")
  private ZonedDateTime createdAt;
}

And after I compile the project, this is the Openapi documentation I get:

openapi: 3.0.1
tags:
- name: Simple API
  description: Operations related to a simple API
paths:
  /v1/auth/create:
    post:
      tags:
      - Simple API
      summary: Create
      description: Create a simple entity
      operationId: create
      requestBody:
        content:
          '*/*':
            schema:
              $ref: "#/components/schemas/Request"
        required: true
      responses:
        "201":
          description: Entity created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
        "500":
          description: Internal server error
components:
  schemas:
    Response:
      required:
      - created_at
      type: object
      properties:
        created_at:
          type: string
          description: Date in ISO 8601 format of YYYY-MM-DDThh:mm:ss.SSSZ in UTC
          format: date-time
          example: 2021-05-26T15:36:19Z
    Request:
      type: object

Note that the request schema is missing and the response is missing a field.

Am I missing something?

The demo project I created can be found here https://github.com/tiagofvalerio/demo