OpenAPI Specs

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

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 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

/* @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

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.