Improve OpenAPI support in Swagger .json and .yaml

[belyaev-andrey]

We need to infer parameter types and add those types to the "definitions" section in

http://localhost:8080/app/rest/v2/docs/swagger.yaml
http://localhost:8080/app/rest/v2/docs/swaggerDetailed.yaml

files.

For example, for the project https://github.com/cuba-platform/sample-session-planner we can create the following descriptor for REST service publication:

<?xml version="1.0" encoding="UTF-8"?>
<services xmlns="http://schemas.haulmont.com/cuba/rest-services-v2.xsd">
    <service name="sessionplanner_SessionService">
        <method name="rescheduleSession" anonymousAllowed="true">
            <param name="newStartDate"/>
            <param name="session"/>
        </method>
    </service>
</services>

It is not easy to add a proper type for the session parameter (it is an entity), therefore, we get the following swagger descriptior:

    post:
      produces:
      - "application/json"
      parameters:
      - originalRef: "#/parameters/sessionplanner_SessionService_rescheduleSession_paramsObject_POST"
        $ref: "#/parameters/sessionplanner_SessionService_rescheduleSession_paramsObject_POST"

  sessionplanner_SessionService_rescheduleSession_paramsObject_POST:
    in: "body"
    name: "paramsObject"
    required: true
    schema:
      properties:
        newStartDate:
          type: "string"
        session:
          type: "string"

But session is not string, its structure is:

public class Session extends StandardEntity {
    protected String topic;
    protected Date startDate;
    protected Date endDate;
    protected Speaker speaker;
}

And this prevents us from generating the proper client application based on the swagger descriptor. Service method parameter types should be properly supported.

[knstvk]

What if you specify the parameter type in rest-services.xml as described here? Will the OpenAPI contain the type?

[belyaev-andrey]

In the documentation we describe only "simple" types, but not ones that might require complex serialization/deserialization. For the description:

        <method name="rescheduleSession" anonymousAllowed="true">
            <param name="session" type="com.company.sessionplanner.entity.Session"/>
            <param name="newStartDate" type="java.util.Date"/>
        </method>

It generates the following description for POST:

      parameters:
      - $ref: "#/parameters/sessionplanner_SessionService_rescheduleSession_paramsObject_POST"
        originalRef: "#/parameters/sessionplanner_SessionService_rescheduleSession_paramsObject_POST"

  sessionplanner_SessionService_rescheduleSession_paramsObject_POST:
    in: "body"
    name: "paramsObject"
    required: true
    schema:
      properties:
        newStartDate:
          type: "string"
          format: "date"
          example: "2005-14-10T13:17:42.16Z"
        session:
          type: "object"
          description: "sessionplanner_Session"

And for GET:

      parameters:
      - $ref: "#/parameters/sessionplanner_SessionService_rescheduleSession_session_GET"
        originalRef: "#/parameters/sessionplanner_SessionService_rescheduleSession_session_GET"
      - $ref: "#/parameters/sessionplanner_SessionService_rescheduleSession_newStartDate_GET"
        originalRef: "#/parameters/sessionplanner_SessionService_rescheduleSession_newStartDate_GET"

  sessionplanner_SessionService_rescheduleSession_newStartDate_GET:
    name: "newStartDate"
    in: "query"
    required: true
    type: "string"
  sessionplanner_SessionService_rescheduleSession_session_GET:
    name: "session"
    in: "query"
    required: true
    type: "string"