oas A language-agnostic tool for documenting your API right from your code, generating an OpenAPI Spec, and sharing it via a URL.

An OpenAPI Spec (formerly known as Swagger) is a standard format for designing and documenting a RESTful API. This tool guides you through setting up an OpenAPI Spec 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 Spec
/* @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
info:
  version: 1.0.0
  title: Petstore API
servers:
- url: https://petstore.com
paths:
  "/pets/{category}":
    post:
      description: List all pets in a category
      parameters:
      - in: path
        name: category
        required: true
        description: Pet category
        schema:
          type: string
          default: all
      - in: query
        name: limit
        description: Amt returned
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Successful response
     requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                search:
                  type: string
                  description: Search pet details
                strict:
                  type: boolean
                  description: Exact matches?
View a full example  View a hosted spec
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 spec 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 Spec 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.

oas host

3. Hosting your Swagger file

For a lot of projects, piping oas generate is the best way to integrate. However, a lot of times you want a URL, either to share to another human or to use with a tool that accepts a URL.

To host your file quickly, just type oas host. You'll need to be logged in via GitHub for this to work (it'll prompt you on your first deploy). You'll get a public URL back that you can share.

Example: http://openap.is/petstore/1.0.2.json

If you push multiple versions, they'll be linked together on the site. The site can be used to version your files, and keep them updated.

npm install rdme -g
rdme swagger file.json

4. 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 Spec 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.