https://github.com/scrive/openapi2slate
An opinionated converter from OpenAPI to Slate Markdown
https://github.com/scrive/openapi2slate
Last synced: about 1 year ago
JSON representation
An opinionated converter from OpenAPI to Slate Markdown
- Host: GitHub
- URL: https://github.com/scrive/openapi2slate
- Owner: scrive
- License: bsd-3-clause
- Created: 2016-11-21T11:09:03.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-10-03T07:52:09.000Z (over 3 years ago)
- Last Synced: 2025-04-16T01:21:02.224Z (about 1 year ago)
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/openapi2slate
- Size: 688 KB
- Stars: 17
- Watchers: 23
- Forks: 6
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenAPI to Slate Markdown
An opinionated and Work in Progress converter from
[OpenAPI](https://www.openapis.org/specification/repo) to [Slate
Markdown](https://github.com/lord/slate).
Created for use by [Scrive](https://github.com/scrive/).
## Usage
```
openapi2slate your_api.json
```
Outputs resulting Markdown + HTML to standard output.
Command line options:
```
--validate Validate the API using Swagger-Parser
--include-internal By default API paths using an 'Internal' tag will be
hidden, this flag includes them too
--search-filter Include the search filter
```
## Our formatting choices
* We use it for http://apidocs.scrive.com/
* Dereferncing is not properly implemented, instead it tries to dereference the
file for you and use that. YMMV.
* API paths are grouped by tags.
* A list of API paths is generated automatically.
* The 'Internal' tag acts in a special way and those API paths are not included
by default, use `--include-internal` to include them.
* You can mark parameters with `x-internalOnly` to make them "Internal"
* API Schema works fairly OK, some features may be missing...
* We render things in Slate Markdown that fits **our** needs and
customisations, so this may not work well for you!