swagger-api / swagger-api/swagger-core
OpenApi doc not beeing generated properly
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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