A community collection of rulesets, configuration, custom plugins and other additions for Redocly CLI. We know our users have some great tips, examples, and code to share, and this is the place to do just that. We would love to have your contributions here too!
Important
Redocly are the repository maintainers, but we can't thoroughly test everything here. Please browse, share, and use what you find at your own risk.
If you're new to Redocly CLI, start with the documentation to get up and running, then come back here to pick out any elements you would like to re-use yourself. To keep up with new developments, either subscribe to the project repository, or sign up for the Redocly product newsletter.
Use the content here as a starting point for your own work.
-
Take a look at what's available in each category, and pick any that you think apply to your situation.
-
Each section links to the documentation for that feature, incase you need an introduction or refresher.
-
Copy and paste the examples you want to use into your own setup, then edit them to fit your own needs.
If you come up with something new, please consider sharing it here by opening a pull request.
Combine existing built-in rules in ways that serve a specific purpose, and make a resuable ruleset.
- Spec-compliant ruleset
- Spot common mistakes
- Security ruleset adds some defensive rules to your description.
There are some fantastic examples of configurable rules in the wild, we hope the list here inspires you to share more of your own!
- Ban certain words from descriptions
- Require
itemsfield for schemas of typearray - Ensure sentence case in operation summaries
POSTSHOULD definerequestBodyschemaGETSHOULD NOT definerequestBodyschemaDELETESHOULD NOT definerequestBodyschema- Info section must have a description
- No
<script>tags in descriptions - Paths should not match a pattern
- API healthcheck rules
- String schemas length defined
- JSON Schema misconfigurations
- Azure APIM unsupported keywords
The custom plugin is the ultimate in extensibility, but it's an advanced feature. Try these plugins for inspiration and to get you started. Rather than including the whole plugin, there are also sections for individual rules and decorators further down.
- Sorting plugin - rules to check sort order and decorators to transform an API description into the correct order. Includes sorting for tags, methods, properties and enum values.
- Tag sorting - put your tags list in alphabetical order.
- Substitute datetime placeholders in an API description - update dates in examples to the current date.
- OpenAI isConsequential - add
x-openai-isConsequential: truespecification extension to GET operations. - Remove extensions - remove any given OpenAPI Extensions from an OpenAPI document.
- Remove unused tags - remove tags that are declared but not used by any operations.
- Azure APIM - remove features unsupported by Azure APIM such as examples.
- Swap summary and description - swap the contents of summary and description fields if they are the wrong way round.
- Validate Markdown - check Markdown in description fields is valid.
- Check code samples - check that an expected list of code samples is present in
x-code-samplesfor every operation.
Share anything that didn't fit the existing categories here.
- Script to re-order an API description and put the top-level properties in a particular order.
Please share your best Redocly CLI usage with us! Each item should be shared in its own pull request, following the existing directory structure and including the README template copied into each folder. Full instructions are in the CONTRIBUTING file.
If there's something you think should be in the collection and it isn't, let us know! Open an issue, and describe the problem you'd like to see solved with Redocly CLI. We can't make promises, but we are pretty sure someone out there will know the answer.