what is the proper way to create a swagger web service in TypeScript

Question

I am part of a project written in TypeScipt and I am trying to add TypeScript Web Server which will be compatible with Swagger.
What is the most basic strategy to implement it, considering easy maintainability.

• For Typescript I have notice that exists 'Typson' library for generating a JSON Model from TypeScript Interface.

• For Swagger, I have tried using 'swagger-node-restify' library, since it supports adding JSON models to swagger.

However, I encounter some problems:

1. Typson doesn't support typeScript syntax of Import - (import {Server} from "restify")
2. I tried to implement the 'swagger-node-restify' example (Pet Example), however the RESPONSE of the localhost:8080/api-docs.json GET Request is missing all the SPEC data of the API. {"apiVersion":"0.1","swaggerVersion":"1.1","basePath":"http://localhost:8080","apis":[{"path":"/api-docs.{format}/pet","description":"none"}]}

Answer 1

I suggest to describe a Swagger compliant API using yaml or json and to generate the server from that.

swagger-server can build APIs on top of express in real time (no source code generation).

There are JavaScript code generators :

• Call the swagger-codegen client with -l nodejs-server

• swagger-node is a great alternative but seems hard to integrate with TypeScript

Answer 2

Yes, you can easily generate Swagger and OpenAPI documents from your TypeScript types by using tsoa. The readme contains all of the setup information that you would need to start using it. It's compatible with express, hapi, koa, and more (via the ability to add your own template for your preferred server type):

https://github.com/lukeautry/tsoa

The advantages that tsoa has over other libraries is:

• it both generates the swagger/OpenAPI document and it also validates the types at runtime

---

(Full Transparency: I am one of the maintainers of tsoa. But I was first a consumer of tsoa and I find it to be a great product... that's why I asked to help maintain it! :) )