Recipes - OpenAPI schema

Eicrud's CLI lets you generate an OpenAPI schema specifying all your services' CRUD and command endpoints.

Info

This allows for integration with OpenAPI tools such as Swagger, Postman and even OpenAPI Generator which lets you generate clients for many languages (java, swift, python... etc.).

Generate a schema

To generate a basic schema simply run.

eicrud export dtos
eicrud export openapi -o-jqs

Note

The option -o-jqs ensures maximum compatibility with generators but suppresses the typing of JSON query parameters

Example of a generated schema

eicrud-open-api.yaml

openapi: 3.0.0
info:
servers:
components:
paths:
  /crud/s/user-profile/one:
    get:
    post:
    patch:
    delete:
      summary: Delete a UserProfile
      parameters: 
      responses:  
  /crud/s/user-profile/batch:
  /crud/s/user-profile/many:
  /crud/s/user-profile/in:
  /crud/s/user-profile/ids:
  /crud/s/user-profile/cmd/can_cannot_cmd:
  /crud/s/user-profile/cmd/search:

You can override parts of the generated schema in eicrud-cli.json.

eicrud-cli.json

{
    "export": {
        // ...
        "openApiBaseSpec": {
            "info": {
                "title": "My Api",
                "version": "2.0.0",
            },
            "servers": [
                {
                    "description": "Production server",
                    "url": "https://prod-domain:3000"
                }
            ]
        }
    }
}

Typed schema

You can use the typeconv package to convert your DTOs into OpenAPI components. The CLI will then embed these components into the generated schema.

eicrud export dtos -cc
npm i -g typeconv@2.3.1
typeconv -v -f ts -t oapi -o eicrud_exports 'eicrud_exports/**.ts' 'eicrud_exports/**/*.ts' 
eicrud export openapi

Warning

To generate DTOs with the convert classes (-cc) option correctly, every class, interface and type in your *.entity.ts and *.dto.ts file must be exported. Additionally, every class member must be separated by a semicolon ;. This allows the script to remove initializations.

Exclude paths & troubleshooting

Like the super-client's export, the OpenAPI export depends on the generated DTOs, check out the exclude and troubleshooting sections for more info.