eclipse / microprofile-open-api

Microprofile open api
Apache License 2.0
131 stars 81 forks source link

Using openAPI 3.0, the schema properties are not generated for a POST request's body params #532

Closed rujiel closed 2 years ago

rujiel commented 2 years ago

For a simple POST example that I have, the schema object that it consumes is not being picked up in openapi, and no properties are shown as options for the POST in the output yaml.

The POST's accept and content type headers also aren't being detected, and / is shown for both. I'm moving to open API from swagger, and in the past with Swagger the accept and content types were auto-detected from the @Consumes and @Produces annotations. I tried the equivalent with @APIResponse (see below) but the information doesn't populate.

For this POST, it seems like boilerplate yaml is being generated. However, the ReviewerDO and its properties do show up in the schemsa list, and for an equivalent GET request the fields are populated. so I'm not sure what's wrong with my POST.

Sample resource

public class ReviewerDO {

    @JsonbProperty
    @NotEmpty
    @Schema(description = "reviewer ID")
    private String id;

    @JsonbProperty("facebook_id")
    @NotEmpty
    @Schema(name = "facebook_id", description = "reviewer facebook ID")
    private String fbId;

    public ReviewerDO(Reviewer rev) {
        this.id = rev.getId().toString();
        this.fbId = rev.getFacebookId();
    }

    public String getId() {
        return id;
    }

    private void setId(String id) {
        this.id = id;
    }

    public String getFbId() {
        return fbId;
    }

    public void setFbId(String fbId) {
        this.fbId = fbId;
    }
}

The POST

@Path("/reviewers")
@Tag(name = "Reviewers", description = "Reviewers")
public class ReviewerResource {

@Inject
ReviewerService service;

@POST
@APIResponses(value = {
    @APIResponse(responseCode = "200", content = {
        @Content(mediaType = "application/json", schema = @Schema(implementation = ReviewerDO.class)) })})
@Operation(summary = "create a reviewer")
@Consumes("application/json")
public Response create(@Parameter ReviewerDO reviewer) {
    String id = service.create(reviewer.getFbId());
    return Response.noContent()
        .location(URI.create(id)).build();
}
}

Generated yaml

    post:
      parameters: []
      requestBody:
        content: {}
      operationId: "create_1_2_3_4"
      responses:
        "200":
          content:
            '*/*':
              schema:
                properties: {}
                type: "object"
                nullable: true
          description: "default response"
        default:
          content:
            '*/*':
              schema:
                properties: {}
                type: "object"
                nullable: true
          description: "default response"

The @RequestBody approach detailed below also doesn't seem to work, the yaml for the post is still all defaults

https://download.eclipse.org/microprofile/microprofile-open-api-1.0/microprofile-openapi-spec.html#_requestbody

rujiel commented 2 years ago

I found the issue: the POST methods with a schema only get documented if both @Consumes and @Produces are specified for the method or the class. In the past I only needed to specify @Consumes for POSTs.

I also didn't need to use APIResponse, should have been using @RequestBodySchema with my class on the method in question