https://github.com/thingful/openapi-spec
https://github.com/thingful/openapi-spec
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/thingful/openapi-spec
- Owner: thingful
- License: mit
- Created: 2016-11-04T11:47:58.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-08-30T14:22:59.000Z (over 8 years ago)
- Last Synced: 2024-11-27T10:36:01.607Z (about 1 year ago)
- Language: JavaScript
- Size: 1.06 MB
- Stars: 8
- Watchers: 3
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - thingful/openapi-spec - (JavaScript)
README
# Thingful OpenAPI Specification
[](https://travis-ci.org/thingful/openapi-spec)
## Steps to finish
1. Enable [Travis](https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI%3A) for your repository (**note**: you already have `.travis.yml` file)
2. [Create GitHub access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/); check `public_repo` on `Select scopes` section.
3. Use the token value as a value for [Travis environment variable](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings) with the name `GH_TOKEN`
4. Make a test commit to trigger CI: `git commit --allow-empty -m "Test Travis CI" && git push`
5. Wait until Travis build is finished. You can check progress by clicking on the `Build Status` badge at the top
6. If you did everything correct, https://thingful.github.io/openapi-spec/ will lead to your new docs
7. **[Optional]** You can setup [custom domain](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) (just create `web/CNAME` file)
8. Start writing/editing your OpenAPI spec: check out [usage](#usage) section below
9. **[Optional]** If you document public API consider adding it into [APIs.guru](https://APIs.guru) directory using [this form](https://apis.guru/add-api/).
10. Delete this section :smile:
## Links
- Documentation(ReDoc): https://thingful.github.io/openapi-spec/
- SwaggerUI: https://thingful.github.io/openapi-spec/swagger-ui/
- Look full spec:
+ JSON https://thingful.github.io/openapi-spec/swagger.json
+ YAML https://thingful.github.io/openapi-spec/swagger.yaml
- Preview spec version for branch `[branch]`: https://thingful.github.io/openapi-spec/preview/[branch]
**Warning:** All above links are updated only after Travis CI finishes deployment
## Working on specification
### Install
1. Install [Node JS](https://nodejs.org/)
2. Clone repo and `cd`
+ Run `npm install`
### Usage
1. Run `npm start`
2. Checkout console output to see where local server is started. You can use all [links](#links) (except `preview`) by replacing https://thingful.github.io/openapi-spec/ with url from the message: `Server started `
3. Make changes using your favorite editor or `swagger-editor` (look for URL in console output)
4. All changes are immediately propagated to your local server, moreover all documentation pages will be automagically refreshed in a browser after each change
**TIP:** you can open `swagger-editor`, documentation and `swagger-ui` in parallel
5. Once you finish with the changes you can run tests using: `npm test`
6. Share you changes with the rest of the world by pushing to GitHub :smile: