oas-tools / oas-cli

Command line interface tool for OAS TOOLS Framework

OAS TOOLS

Warning

OAS Tools package has been renamed from oas-tools to @oas-tools/core

Quickstart

Initialize a new OAS Tools project from the CLI

> 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

Select server, answer the questions and you'll get a running server with OAS Tools.

More information in our web page

Contributing guidelines

We greatly appreciate community contributions, that's why we have created a document stating clear guidelines for contributing to OAS Tools. We also encourage you to participate in discussions and activate notification for our announcements in the organization's discussions dashboard

License

Copyright 2018, ISA Group, University of Sevilla

For technical inquiry please contact to engineering team.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

oas-cli's Issues

Pluralize "get all" (i.e. find many) endpoints in the generated OpenAPI document

Context

Using the CLI to generate an OpenAPI document from an entity resource file for a given resource like User.

Issue

The CLI generates the following lines containing an operationId that should probably be plural:

  /api/v1/users:
    get:
      description: Returns all users
      operationId: getUser
      responses:
        200:
          description: User list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/user'

Note how the endpoint and description are plural as expected, and the success response is an array, yet the operationId is singular.

In turn, when generating a server based on this OpenAPI document, we'll end up with a controller that looks like this:

export function getUser(req, res) {
    service.getUser(req, res);
}

The function name would seem to imply that we'll only be getting one user back. However, the return value is going to be an array with any number of users.

Expected outcome

Instead of getUser, the operation should be named getUsers.

The code

I haven't done a thorough check, but this appears to be where it's happening:

oas-cli/templates/file/oas-doc.hbs

Lines 13 to 14 in bf53dd6

	description: Returns all {{lookup ../resources @index}}
	operationId: get{{lookup ../Resource @index}}

[BUG] ERR_MODULE_NOT_FOUND when generating server with Dockerfile

Describe the bug

When initializing a new server using the CLI tool, if the option to generate the Dockerfile is set the server will throw an error when executing npm start:

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'server.js' imported from E:\Alex\Desktop\adsdsd\generated-server\index.js
    at new NodeError (node:internal/errors:371:5)
    at packageResolve (node:internal/modules/esm/resolve:884:9)
    at moduleResolve (node:internal/modules/esm/resolve:929:18)
    at defaultResolve (node:internal/modules/esm/resolve:1044:11)
    at ESMLoader.resolve (node:internal/modules/esm/loader:422:30)
    at ESMLoader.getModuleJob (node:internal/modules/esm/loader:222:40)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:76:40)
    at link (node:internal/modules/esm/module_job:75:36) {
  code: 'ERR_MODULE_NOT_FOUND'
}

To Reproduce

Steps to reproduce the behavior:

1. Create an OpenAPI document
2. Run npx @oas-tools/cli init and select server
3. Select the option to generate a Dockerfile
4. Once generated, run npm start inside the new server directory.

Expected behavior

The server should start normally, installing all dependencies previously.

incorrect double negation in template

oas-cli/templates/server/index.js.hbs

Line 61 in 7d9e6b2

if (config.middleware.swagger?.disable !== false) {

the line should display the output if disable !== true in stead of false

[BUG] Array properties staring from an entity resource

Describe the bug
When we declare arrays inside the entities and execute the cli for the creation of the oas-doc from a json. These are taken as their type in javascript typeof [1,2,3,4] // Returns "object".
To Reproduce
Steps to reproduce the behavior:

1. Create a json file like

[
    {
        "id": 1,
        "name": "User",
        "email": "[email protected]",
        "pets": [ 
           {
               "id": 1,
               "petName": "Garfield",
               "type": "Cat"
           }
        ]
    }
]

2. Exec npx @oas-tools/cli init to create OpenAPI File

[BUG] Awkward phrasing in prompt message

Describe the bug

Awkward phrasing in serverPrompt and filePrompt

To Reproduce

Steps to reproduce the behavior:

1. Go to 'serverPrompt'
2. Scroll down to 'line 5'
3. See message

Steps to reproduce the behavior:

1. Go to 'filePrompt'
2. Scroll down to 'line 93'
3. See message

Expected behavior

A clear and concise message explaining what will happen.

Additional context

None.

`204` should be an integer in the generated OpenAPI document

When generating an OpenAPI document from an entity resource file, the 204 status is the only one that is generated as a string instead of as an integer.

Other (non-204) response statuses look like the following:

responses:
    200:
      description: Item found by id

For 204s, it will instead look like this:

responses:
    "204":
      description: Item deleted

To Reproduce

Steps to reproduce the behavior:

1. Use an entity resource file to create an OpenAPI document with the CLI
2. In the interactive prompt, for any given entity, select the HTTP methods PUT and/or DELETE
3. Check the generated OpenAPI document to see that the 204s are noted as strings

Expected behavior

Instead of "204", the status should simply be 204 (no quotation marks).