Define your API Standards
Make your team's API Standards and Style Guide easy to learn and easy to follow. Optic guides and supports developers designing APIs.
Teams use Optic's checks to:
- Detect breaking changes between two versions of an OpenAPI file.
- Enforce an API Style Guide.
- Enforce their unique API versioning strategy.
- Require OpenAPI specs use certain
x-
extensions.
How are Optic Checks different from other API linting tools?
- Our Typescript SDK makes it easy to express a complete API style guide.
- Write Rules about change. Optic Checks can run against two API versions (before and after) to help enforce your versioning strategy, deprecation policy and to detect breaking changes.
- Exclude false positives. Sometimes we can't change the API to pass a rule because doing so would be a breaking change. Optic understands this and makes it possible to tune your checks, so they run in the right places and are trusted by developers.
Writing your own checks (in beta)
The Optic Checks SDK is still in Beta and has not reached stability. We're working closely with several teams like Snyk to build the right SDK and release it publicly in coming months. If you would like to join that beta you can by setting up a quick call here.
Using Built-in Checks
First run optic init
in your repository:
optic init
This command will find all the OpenAPI specifications in your repo and add them to your optic.yml
file:
files:
- id: todo-api
path: specs/todo-openapi.yaml
ruleset:
- "breaking-changes"
- "naming":
pathComponents: camelCase
Right now you can configure the naming
checks as described here.
More built-ins are coming soon. If you have an idea for a new built-in ruleset, feel free to open an Issue here.
Running API Standards in CI
Optic's changelog view can show the results of all your API standards. Just include the --web
flag. This computes the changelog locally and includes it via a URL to Optic's visual changelog view (we do not save the data).
optic diff openapi.yaml --base main --check --web
Enforce your API Standards in CI
You can set up Optic Cloud to test all your team's API changes and apply the API Standards during CI. Learn more about setting up Optic Cloud here.