swagger-api / swagger-api/swagger-core

OpenApi doc not beeing generated properly

Open
#4,842 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked demo project and reproduce generation using SimpleController, RequestDto, and ResponseDto with swagger-maven-plugin-jakarta 2.2.28. Compare the generated OpenAPI YAML with the DTO annotations, focusing on the missing Request fields and Response.id. Done means both schemas retain the annotated fields and constraints shown in the example.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.