Generate your API code from OpenAPI/Swagger without effort!

Boost your development and save a lot of time

---

Introduction

How many times did you have to create manually all models and API calls for the app or external service that you were working on? And even worst… When they have some OpenAPI standard!

Yes, I know, even Swagger provides you an application that generates this code, but at the moment I tried it, the result code was messy and hard to configure (also heavy), and for the current time, there are more applications that provides you a lot of code, but I want to get my own by myself with native support for JavaScript.

So around two years ago I wrote my first approach to solve this for myself, that code was too bad, so I never publish it, but some weeks ago I need the solution again for Open API V3. So… I had to write it again from scratch, but this time with a bit more planning.

About the project

The project is Open Source, you can star or fork it on GitHub: https://github.com/ProtocolNebula/ts-openapi-generator.

Is written in TypeScript but is only to generate the files, so don’t worry, it will be useful even for your assembly application ;).

At this moment it only comes with an Angular 2 template, but you can create your own or wait until more are added.

You can push templates and contribute to the project :).

Supported documents

It currently supports Swagger 1, Swagger 2 (OpenAPI), and OpenAPI V3.

The script use converters (api-spec-converter) to OpenAPI V3 which are automatically applied to the file.

Is planned to support more standard documents.

OpenAPI V3 specs support

At this moment not all specs are supported, there are some a bit hard to implement in some languages, like OneOf or AnyOf, there are planned solutions but will take some days to check that those methods are easy to customize.

Installation and use

Install globally

If you wanna use this at “freestyle” (normal CLI) you have to install it globally:

npm i -g @protocolnebula/ts-openapi-generator

Install locally

On the other hand, if you prefer to automatize this process into a project, you have to install it locally:

npm i @protocolnebula/ts-openapi-generator

How to use

There are some ways to initialize, the most common is to launch the script (pending command name revision), for example, if you launch:

transform-swagger -f https://raw.githubusercontent.com/ProtocolNebula/ts-openapi-generator/main/examples/openApiFiles/passportescaperoom.com.json -o src/generatedApi/ -t angular2

You can find a new folder structure: src/generatedApi with the generated files.

You can check the examples in the GitHub project.

This script will do:

• -f: Specify which file will be parsed or downloaded (you can specify some local file).
• -o: output folder in which the data will be generated (the folder will be cleared after each execution).
• -t: Template to use, in this case, angular2, you can create your template and set it as a relative path. (EX: ./templates/myPHPTemplate)

Alternatively you can create a json config file with this settings:

{
  "file": "https://raw.githubusercontent.com/ProtocolNebula/ts-openapi-generator/main/examples/openApiFiles/passportescaperoom.com.json",
  "outputFolder": "src/generatedApi/",
  "template": "angular2",
  "saveFile": "tempOpenApiFile"
}

And launch the script with the command:

transform-swagger --config-file yourSettings.json

Using the generated files

The angular2 template has a dependency (as you can see in the generated files) which is “ApiBase”, this is my custom layer for service requests in my angular project, but you can create your one (just change the templates).

If want to use the current Angular 2 template, just copy ApiBase folder to your project at the same parent as the generated files (you can manually download from GitHub instead):

cp -r node_modules/ts-openapi-generator/ApiBase src/ApiBase

At this point, you can use the generated API files in your project using normal imports, that’s all (check that are provided as root).

Custom templates

Please, note that because this project is in an earlier phase, some changes can be done to the templating system.

As described in the template tutorial, you can do a custom template, summarizing:

1. Copy and paste templates/angular2 folder to your desired folder (or into templates/ if you wanna push to the main repo).
2. Modify the files inside the folder.
3. Generate with your templates! (-t option)

---

At this point, you should create and use your custom APIs and Models consumed from any OpenAPI file.

Contribute to the project

Don’t forget that this is an Open Source project, so you can contribute in many ways, for example, Starring the project or Pushing code (doing a fork).

You can also contribute with money to the project or other projects I want to make (just check the contribute option in GitHub).

I hope this will be useful to you!