OpenAPI+ TSOA

Troy Rhinehart

Code is Documentation

– Nobody

Code is Documentation, when Documentation is Code

– You 😅🙏

Create

Using Typescript + TSOA, create your interfaces and output a swagger.json

1.

Generate

Using the swagger.json, generate a UI and Client library in the language of your choice

2.

Consume

Using the Client, interact with the interfaces with type safety and feature parity

3.

Create

@Route("users")
export class UsersController extends Controller {
  @Get("{userId}")
  public async getUser(
    @Path() userId: number
  ): Promise<User> {
    return new UsersService().get(userId, name);
  }

  @SuccessResponse("201", "Created User")
  @Post()
  public async createUser(
    @Body() requestBody: UserCreationParams
  ): Promise<User> {
    this.setStatus(201); // set return status 201
    return new UsersService().create(requestBody);
  }
}

Generate

openapi 
  --useOptions
  --useUnionTypes
  --name "API Client"
  --input "https://<API>/swagger.json"
  --output ./src/generated
  --request ./src/request.ts
  --indent 2

Consume

import { Client } from 'my-api-client';

const client = new Client({ BASE: 'https://<API>' });

client.users.getUser({ userId: 1 }).then(user => {
  console.log('User 1', user);
});

DEMO

Code is Documentation

By gingur

Code is Documentation

Code is Documentation, when Documentation is Code

  • 55