Skip to content
main
Switch branches/tags
Code

Files

Permalink
Failed to load latest commit information.

oas

Working with Swagger and OpenAPI definitions is hard. This makes it easier.

Build

Installation

npm install oas

CLI

The CLI tool makes creating API definition files easier. It currently supports Swagger 2.0 and OpenAPI 3.x documents.

Usage

Go to a directory with your API, and type:

oas init

It will walk you through how to document your API with a OpenAPI 3.0 Spec.

Swagger Inline

oas uses swagger-inline which allows you include a little OpenAPI snippet in a comment above your code, and collects them all together into one OpenAPI file:

/*
 * @oas [get] /pet/{petId}
 * description: "Returns all pets from the system that the user has access to"
 * parameters:
 *   - (path) petId=hi* {String} The pet ID
 *   - (query) limit {Integer:int32} The number of resources to return
*/
route.get("/pet/:petId", pet.show);

You need to start with @oas [method] path, but everything below it is a valid Path Definition.

You can also do inline parameters, which are shorthand for parameters. They aren't valid OpenAPI properties but swagger-inline knows how to compile them:

- (in) name=default* {type:format} Description

Tooling

This library also exposes a set of tooling to help you manage OpenAPI definitions. You can access it by loading:

require('oas')

Also exposed within the main oas export is an Operation class that can help you manage and retrieve specific data from an API operation.

To use a compiled version of this offering within a browser, you can load oas/dist