docs(repo): add API Stylebook to README #2346
Merged
Conversation
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
pamgoodrich
previously approved these changes
Nov 21, 2022
README.md
Outdated
| - [OWASP Top 10](https://apistylebook.stoplight.io/docs/owasp-top-10) - Set of rules to enforce [OWASP security guidelines](https://owasp.org/www-project-api-security/). | ||
| - [URL Style Guidelines](https://apistylebook.stoplight.io/docs/url-guidelines) - Set of rules to help developers make better and consistent endpoints. | ||
|
|
||
| And there are also rulesets created by many companies to improve their APIs. You can use these as is to lint your OpenAPI descriptions, or use these as a reference to learn more about what rules you would want in your own ruleset: |
There was a problem hiding this comment.
You can probably remove the "And" at the beginning of the sentence since you have also. So it would read "There are also rulesets..."
README.md
Outdated
| - [Adidas](https://github.com/adidas/api-guidelines/blob/master/.spectral.yml) - Adidas were one of the first companies to release their API Style Guide in a written guide _and_ a Spectral ruleset. Lots of good rules to try in here. | ||
| - [APIs You Won't Hate](https://github.com/apisyouwonthate/style-guide) - An opinionated collection of rules based on advice in the [APIs You Won't Hate](https://apisyouwonthate.com/) community. | ||
| - [Azure](https://github.com/Azure/azure-api-style-guide/blob/main/spectral.yaml) - Ruleset and complimentary style guide for creating OpenAPI 2 or 3 definitions of Azure services. | ||
| - [Box](https://github.com/box/box-openapi/blob/main/.spectral.yml) - Lots of [Custom Functions](https://meta.stoplight.io/docs/spectral/ZG9jOjI1MTkw-custom-functions) being used to enforce good practices that the Box API governance folks are interested in. | ||
| - [DigitalOcean](https://github.com/digitalocean/openapi/blob/main/spectral/ruleset.yml) - Keeping their OpenAPI nice and tidy, enforcing use of `$ref` (probably to minimize conflicts), naming conventions for Operation IDs, and all sorts of other handy OpenAPI tips. | ||
| - [Tranascom](https://github.com/transcom/mymove/blob/master/swagger-def/.spectral.yml) - Don't even think about using anything other than `application/json`. | ||
| - [Zalando](https://apistylebook.stoplight.io/docs/zalando-restful-api-guidelines) - Based on [Zalando's RESTFUL API Guidelines](https://github.com/zalando/restful-api-guidelines), covers a wide-range of API topics such as versioning standards, properties naming standards, the default format for request/response properties, and more. |
There was a problem hiding this comment.
properties naming standards > property naming standards?
heitortsergent
force-pushed
the
docs/readme-rulesets
branch
from
fa050bf to
bfec332
Compare
pamgoodrich
approved these changes
Nov 21, 2022
PagoNxt-Trade
pushed a commit
to PagoNxt-Trade/spectral
that referenced
this pull request
Dec 1, 2022
PagoNxt-Trade
pushed a commit
to PagoNxt-Trade/spectral
that referenced
this pull request
Dec 1, 2022
PagoNxt-Trade
pushed a commit
to PagoNxt-Trade/spectral
that referenced
this pull request
Dec 1, 2022
PagoNxt-Trade
pushed a commit
to PagoNxt-Trade/spectral
that referenced
this pull request
Dec 1, 2022
PagoNxt-Trade
pushed a commit
to PagoNxt-Trade/spectral
that referenced
this pull request
Dec 1, 2022
|
🎉 This PR is included in version 6.7.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #2315.
Checklist
Does this PR introduce a breaking change?