Render an OpenAPI specification

An io-ts-http specification contains a superset of an OpenAPI specification. api-ts provides @api-ts/openapi-generator to produce an OpenAPI specification from your io-ts-http API specification. This lets you plug your API specification into the existing OpenAPI ecosystem to HTTP clients for languages other than TypeScript. These clients won't be as ergonomic or type-safe as an api-ts HTTP client.

Use openapi-generator

As before, first edit your package.json file to add our new dependencies (highlighted):

{
  "name": "api-ts-example",
  "scripts": {
    "build": "tsc --lib es2015 --esModuleInterop *.ts"
  },
  "dependencies": {
    "@api-ts/express-wrapper": "1.0.0-beta.20",
    "@api-ts/io-ts-http": "0.2.0-beta.9",
    "@api-ts/response": "0.1.2-beta.2",
    "@api-ts/superagent-wrapper": "0.2.0-beta.13",
    "io-ts": "2.1.3",
    "superagent": "9.0.1"
  },
  "devDependencies": {
    "@api-ts/openapi-generator": "0.2.0-beta.6",
    "@types/express": "4.17.13",
    "@types/node": "18.6.1",
    "@types/superagent": "4.1.15",
    "typescript": "4.7.4"
  }
}

And install it by running:

$ npm install

The openapi-generator requires our TypeScript compiler settings to be specified in a tsconfig.json file, so create one like this:

{
  "include": ["*.ts"],
  "compilerOptions": {
    "lib": ["es2015"],
    "esModuleInterop": true
  }
}

Invoke the openapi-generator by running:

$ npx openapi-generator --input ./index.ts --output ./api.json

This will produce a file api.json with the following content:

{
  "openapi": "3.1.0",
  "info": {
    "title": "api-ts-example",
    "version": "0.1.0"
  },
  "paths": {
    "/hello/{name}": {
      "get": {
        "summary": "GetHello",
        "description": "",
        "parameters": [
          {
            "name": "name",
            "schema": {
              "type": "string"
            },
            "required": true,
            "in": "path",
            "description": ""
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {}
  }
}