-
Notifications
You must be signed in to change notification settings - Fork 28
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
3 additions
and
47 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,52 +1,8 @@ | ||
| # oas | ||
| [](https://github.com/readmeio/oas) | ||
|
|
||
| Creating Swagger / OpenAPI Spec files is hard. This makes it easier. | ||
|
|
||
| [](https://readme.com) | ||
|
|
||
| This tool currently supports [Swagger 2](https://swagger.io/specification/v2/) and [OpenAPI 3.0](https://swagger.io/specification/). | ||
|
|
||
| ## Installation | ||
|
|
||
| npm install oas -g | ||
|
|
||
| ## 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 | ||
|
|
||
| Rather than trying to juggle one gigantic repo, `oas` uses something called [swagger-inline](https://github.com/readmeio/swagger-inline). It lets you include a little swagger snippet in a comment above your code, and collects them all together into one Swagger file: | ||
|
|
||
| ```javascript | ||
| /* | ||
| * @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 [Swagger Path Definition](http://swagger.io/specification/#pathItemObject). | ||
|
|
||
| You can also do **inline parameters**, which are shorthand for parameters. They aren't valid Swagger, however Swagger Inline knows how to compile them: | ||
|
|
||
| ``` | ||
| - (in) name=default* {type:format} Description | ||
| ``` | ||
|
|
||
| ## Host your Swagger file | ||
|
|
||
| Hosting Swagger files is hard! So, we have an online component that hosts your Swagger file for you. Just type the following to get a URL: | ||
|
|
||
| oas host | ||
|
|
||
| This will upload your Swagger file and give you a URL you can use. | ||
| This is the monorepo for the following OpenAPI-related projects: | ||
|
|
||
| * [oas](https://github.com/readmeio/oas/tree/master/packages/cli) | ||
| * [@readme/oas-tooling](https://github.com/readmeio/oas/tree/master/packages/tooling) |