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.

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.

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.