LiveRamp / reslang

A language for describing resource-oriented APIs & turning them into Swagger or resource diagrams. Oriented around the concepts we want to expose in the APIs.
Apache License 2.0
23 stars 7 forks source link

Nullable pagination strings #174

Closed cjea closed 3 years ago

cjea commented 3 years ago

Description

RFC API-3 dictates that pagination fields and hyperlinks are nullable (not undefined) in certain cases. This PR adds a nullable field to the generated OpenAPI, which is the correct way in OpenAPI 3.0.x (docs).

Thanks @zhesah for reporting this.

Test

Using buyer-api-v2 to test, I generated new swagger with:

./reslang --stdout ~/code/api-specs/specs-draft/buyer-api-v2 > \
  ~/code/api-specs/specs-draft/buyer-api-v2/out.swagger.yaml

and confirmed that it has nullable pagination fields:

_pagination:
          type: object
          properties:
            after:
              type: string
              nullable: true

Then I generated typescript code with

yarn add global @openapitools/openapi-generator-cli &&
  yarn openapi-generator-cli generate -i specs-draft/buyer-api-v2/out.swagger.yaml \
    -g typescript-node -o generated-sources/openapi

Finally, confirmed that the interfaces have nullable strings. For example, in generated-sources/openapi/model/v2SegmentMultiResponsePagination.ts:

export class V2SegmentMultiResponsePagination {
    /**
    * This field is a cursor to be passed as a query parameter in subsequent, paginated searches. It allows the next request to begin from where the current search left off. When \"after\" is  null, there are no more records to fetch for this search.
    */
    'after'?: string | null;

    static discriminator: string | undefined = undefined;

    static attributeTypeMap: Array<{name: string, baseName: string, type: string}> = [
        {
            "name": "after",
            "baseName": "after",
            "type": "string"
        }    ];

    static getAttributeTypeMap() {
        return V2SegmentMultiResponsePagination.attributeTypeMap;
    }
}
ops-github-DU4JOAWE commented 3 years ago

This change is Reviewable