readmeio / Oas
Programming Languages
Projects that are alternatives of or similar to Oas
oas
Working with Swagger and OpenAPI definitions is hard. This makes it easier.
Installation
npm install oas
CLI
The CLI tool makes creating API definition files easier. It currently supports Swagger 2 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
Host your API definition
Hosting API documentation is hard so, we have an online component that hosts your OpenAPI/Swagger file for you. Just type the following to get a URL:
oas host
This will upload your API definition and give you a public URL you can use.
Tooling
This library also exposes a set of tooling to help you manage OpenAPI definitions. You can access it by loading:
require('oas/tooling')
To use a compiled version of this offering within a browser, you can load
oas/.tooling
Components available are the following:
-
oas/tooling
: An OAS class can help you discover operations within a large OpenAPI file. -
oas/tooling/operation
: An Operation class that can help you manage and retrieve specific data from an API operation. -
oas/tooling/utils
-
findSchemaDefinition
: Function to assist with$ref
lookups. -
flattenSchema
: Function to reduce a schema definition into a singular list. -
getSchema
: Retrieve the firstrequestBody
schema on an operation. -
parametersToJsonSchema
: Warehouse method to reduce an operation down into a JSON Schema-compatible representation.
-