swagger-core annotations required to specify HTTP requestBody form parameters?

Open Source Swagger OS
, , ,
1

Originally posted by wichers on June 17, 2020

This is related to my other question today: </t/how-to-suppress-requestbody-generation-in-openapi-spec-using-swagger-maven-plugin/687>. I’m trying to now figure out how to use swagger-core annotations to specify requestBody form parameters. What I want to generate is described here: https://swagger.io/docs/specification/describing-request-body/ in the section “Form Data”. I specifically want to generate the .yaml described in the box under: “In OpenAPI 3.0, form data is modelled using a type: object schema where the object properties represent the form fields:”

Here is my relevant swagger-core annotated code:

@Path(“/Test00020”)

public class Test00020 extends HttpServlet {

      @Override

      @POST

      @Operation (

              summary = "Ask something, get something back.",

              requestBody = @RequestBody( description = "Form POST parameters in request body", required = true,

                      content = @Content( schema = @Schema(implementation = Object.class,

                                     name = "Test00020" ))))

      @Consumes(MediaType.APPLICATION\_FORM\_URLENCODED)

      @Produces(MediaType.TEXT\_HTML)

      public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { ...

which results in this .yaml:

paths:

/Test00020:

  post:

    summary: Ask something, get something back.

    operationId: doPost

    requestBody:

      description: Form POST parameters in request body

      content:

        application/x-www-form-urlencoded:

          schema:

            type: object.    <-- Good up to here, but properties: block missing (see below)

      required: true

    responses:

      default:

        description: default response

        content:

          text/html: {}

This is pretty close, but it is missing the parameter name and type param properties in the request body schema:

          properties:

            Test00020:          # <!--- form field name

              type: string

I couldn’t find any example of how to actually do this, and my trial and error got me this far. The name = “Test00020” element of the Content Schema is being ignored. Any clue how I fix my annotations to get it to work properly?

2

Originally posted by frantuma on June 24, 2020

As mentioned in my reply to your other question, swagger-core 2.x reader targets JAX-RS and its implementations: a typical APPLICATION_FORM_URLENCODED endpoint would be implemented e.g. in Jersey like this one processed as this test

However your approach is almost right (using @RequestBody with @Content and @Schema) but adding schema properties via annotation is not (yet) supported. You have 2 options

  1. create a class representing your schema with properties, and use that in the implementation field, like:
class Test00020RequestBody {

  public String Test00020;

}

@Path("/Test00020")

  public class Test00020 extends HttpServlet {

  

          @Override

          @POST

          @Operation (

                  summary = "Ask something, get something back.",

                  requestBody = @RequestBody( description = "Form POST parameters in request body", required = true,

                          content = @Content( schema = @Schema(implementation =Test00020RequestBody.class))))

          @Consumes(MediaType.APPLICATION_FORM_URLENCODED)

          @Produces(MediaType.TEXT_HTML)

          public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { ...

or use a filter to programmatically define exactly what you need