Guide27 November, 2022

Creating a simple app with OAS Tools framework

Quickstart

Using the CLI

The command line interface incorporates the necessary functionality to initialize a REST service from an OpenAPI document as well as to initialize it from an entity resource.

To initialize the CLI tool, run the following command (without the > sign):

> npx @oas-tools/cli init

It will prompt the following menu, asking which type of resource will be initialized:

? Select a resource to initialize (Use arrow keys)
> Server
  Module
  Development environment
  OpenAPI File

Staring from an entity resource

In order to initialize a REST service from an entity resource, you will first need to generate a valid OpenAPI document. Your entity resource must be written in a YAML or JSON file and should look like this:

[
    {
        "id": 1,
        "name": "User",
        "email": "user@example.com"
    },
    {
        "id": 1,
        "petName": "Garfield",
        "type": "Cat"
    }
]

Note that in the example above we have declared an array containing two types of resources: A User with id, name and email attributes, and a Pet with id, petName and type attributes. OAS Tools CLI is capable of interpret both resources and generate a valid OpenAPI document. In case only one resource is provided, there is no need to declare it as an array, an object can be directly passed to the CLI, too.

Once your resource file is ready, select the fourth option in the menu prompted after running npx @oas-tools/cli init command before.

? Select a resource to initialize (Use arrow keys)
  Server
  Module
  Development environment
> OpenAPI File

It will ask you for your resource file, navigate to the directory it is in and select it. Then it will read your file and ask some questions about it.

? Select your resources file '/testResource.json'
? Choose OpenAPI version '3.1'
? Enter a title for the described API 'Autogenerated Api'
? Enter a description for the described API 'Generated with OAS TOOLS CLI'
? Provide a name for the resource containing {id,name,email} 'User'
? Which will be the id property for User 'id'
? Specify which operations will be available for User 'GET, POST, PUT, DELETE'
? Provide a name for the resource containing {id,petName,type} 'Pet'
? Which will be the id property for Pet 'id'
? Specify which operations will be available for Pet 'POST, DELETE'
? Choose the preferred format for the OpenAPI Document 'YAML'
? Where will be file generated? 'oas-doc.yaml'
? Generate file with this options? (Y/n)

Once all the question has been answered, a new OpenAPI file will be generated with the name specified. After that, follow the steps in the section below to generate a server from the OpenAPI declaration.

Starting from the OpenAPI document

Having a valid OpenAPI document, select the first option in the menu prompted after running npx @oas-tools/cli init command:

? Select a resource to initialize (Use arrow keys)
> Server
  Module
  Development environment
  OpenAPI File

It will ask the following questions about the generated server:

? Where will be files generated? 'generated-server'
? Port in which the server will be listening '8080'
? Specify the path to the OpenAPI Document 'oas-doc.yaml'
? Choose the preferred format for the OpenAPI Document 'YAML'
? Dereference OpenAPI document? 'No'
? Choose the preferred Javascript convention for your server 'ECMAScript Modules (ESM)'
? Will the server run inside a container? 'Run normally'
? Compress files in ZIP and delete? 'No'
? Generate server with this options? (Y/n)

Once the server is generated, you can cd <generated-server> and run:

> npm start

Without using the CLI

Assume the following OpenAPI document, save it to oas-file.yaml:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Quickstart
  description: Quickstart for OAS-Tools
paths:
  /api/v1/entity:
    get:
      x-router-controller: EntityController
      operationId: getEntity
      responses:
        '200':
          description: Success
          content:
            application/json:
                schema:
                  $ref: '#/components/schemas/entity'
components:
  schemas:
    entity:
        type: object

Start by creating a new Node.js project and install express and OAS Tools core:

> npm init
> npm install --save express @oas-tools/core

If you want to use ESM syntax, insert "type": "module" at the root level into the generated package.json. Note that OAS Tools is compaible with both, ESM/import and CommonJS/require syntax.

Place your OpenAPI document under /api/oas-file.yaml, and create index.js and controllers/EntityController.js.

Your file structure should look like this:

server
  ├── api
  |   └── oas-file.yaml
  ├── controllers
  |   └── EntityController.js
  ├── node_modules
  |   └── @oas-tools
  |       └── core
  ├── index.js
  ├── package.json
  └── package-lock.json

Open controllers/EntityController.js and export a function with the same name as the operationId specified in the OpenAPI document:

//EntityController.js

module.exports.getEntity = function get(req, res) {
  res.send({entity: "This is an entity object"});
};

Finally, create the server entrypoint in the index.js file:

const http = require('http');
const express = require("express");
const oasTools = require("@oas-tools/core");
const app = express();

app.use(express.json());
const serverPort = 8080;

oasTools.initialize(app).then(() => {
    http.createServer(app).listen(serverPort, () => console.log("Server started!"));
})

Once everything is done, run node index and open your new server docs in your browser.

Quickstart

Using the CLI

Staring from an entity resource

Starting from the OpenAPI document

Without using the CLI

alesancor1