oas A language-agnostic tool for documenting your API right from your code, generating an OpenAPI Definition.

The OpenAPI Specification (formerly known as Swagger) is a standard format for designing and documenting a RESTful API. This tool guides you through setting up an OpenAPI Definition from the command line, writing some documentation in the comments above the actual code (sorta like JavaDocs or similar tools), and compiling it into a shareable YAML or JSON file.

GitHub   ·    Support   ·    NPM
Convert code comments… …into an OpenAPI Definition
/* @oas [post] /pets/{category}
 * description: "List all pets in a category"
 * parameters:
 * - (path) category=all* {String} Pet category
 * - (query) limit {Integer:int32} Amt returned
 * - (body) search {String} Search pet details
 * - (body) strict {Boolean} Exact matches?

routes.get('/pets/:category', getPets);
openapi: 3.0.1
  version: 1.0.0
  title: Petstore API
- url: https://petstore.com
      description: List all pets in a category
      - in: path
        name: category
        required: true
        description: Pet category
          type: string
          default: all
      - in: query
        name: limit
        description: Amt returned
          type: integer
          format: int32
          description: Successful response
              type: object
                  type: string
                  description: Search pet details
                  type: boolean
                  description: Exact matches?
View a full example
npm install oas -g
oas init

1. Getting Started

Getting started is easy! You just install the Node command line tool from npm. Don't worry if you don't write Node, since the tool works on any language.

Once it's installed, run oas init and it'll walk you through the creation of your Swagger file. You can name it anything, and it'll use either JSON or YAML based on the file extension you pick.

/* @oas [get] /pet/{petId}
 * description: "Return all pets"
 * parameters:
 * - (path) petId=hi* {String} The pet ID
 * - (query) limit {Integer} Amt returned

2. Documenting your API inline

There's a lot of ways to create a OAS file, but doing it right in the code is our favorite. It makes it so that your definition is always up to date with the code, and makes it easy to integrate with dev tools.

Don't be scared… it's mostly just the standard OpenAPI Spec YAML format! However, rather than keeping it all the "paths" section of a file, you do it right inline.

The first line

The first line uses a special syntax, which is used to find relevant comments. You start it with @oas, followed by the method, followed by the URL, and then (optionally) the summary. After that, it's just the standard YAML OAS format.

For example: @oas [get] /get/{petId} Get pets

Param shorthand

Defining a simple parameter in OAS is extremely verbose! So, we've created a parameter shorthand. If you want something more complicated, you can always just use the full paramter notation.

Here's a simple example: (query) limit=5* {Integer:int32} Amount returned

It has a lot of info packed into a short space: the type of param (query), the name (limit), the default value (5), that it's required (*), the type (Integer), the format of the type (int32) and the description ("Amount returned"). Almost all of these are optional, you can do something as simple as (query) limit.

Learn More

oas generate --pretty

3. Generating a Swagger file

Once you're done describing your API, you can generate an OpenAPI Definition using oas generate.

When you run it, it'll look through all your files for @oas blocks, and compile them into a single file. By default, this

Like color? You can use oas generate --pretty to pretty print it out.

npm install rdme -g
rdme swagger file.json

3. Uploading to ReadMe

This tool is completely open source and free! However, if you also use ReadMe for documenting your API, we make it really easy to upload your OpenAPI Definition via the command line like you read above.

Instead of using oas, you'll have to use rdme. It still compiles the spec in a similar way, however the syntax is slightly different!

The easiest way to get started is to add a new API in your ReadMe account, and we'll give you instructions on how to set it up.