Skip to content

Commit f38977a

Browse files
committed
update readme
1 parent edef963 commit f38977a

File tree

11 files changed

+47
-986
lines changed

11 files changed

+47
-986
lines changed

README.md

Lines changed: 8 additions & 224 deletions
Original file line numberDiff line numberDiff line change
@@ -1,239 +1,23 @@
11

22
![GitHub Repo stars](https://img.shields.io/github/stars/opticdev/optic?style=social) ![GitHub contributors](https://img.shields.io/github/contributors-anon/opticdev/optic?style=social) ![npm](https://img.shields.io/npm/dm/@useoptic/openapi-io?style=social) ![license](https://img.shields.io/github/license/opticdev/optic?style=social)
33

4-
# Optic - the CI tool that improves your APIs
5-
Optic helps you ship a better API by making it easy for teams to use OpenAPI. Prevent breaking changes, publish accurate documentation and improve the design of your APIs.
4+
# Optic
65

7-
![Screenshot 2023-06-14 at 12 55 11 PM](https://github.com/opticdev/optic/assets/5900338/a446bac2-06b6-40bd-a7d4-42f1cc3621ea)
6+
🧠 **Generate and update OpenAPI** from test traffic
87

8+
🤩 **Catch Breaking Changes and apply Lint rules** with the same tool
99

10-
**Install**
10+
⚡️ **Generate API Changelog** between any two git commits
11+
12+
### Install
1113
```bash
1214
npm install -g @useoptic/optic
1315
```
14-
---
15-
16-
## Run locally
17-
18-
### Prevent breaking changes using `optic diff`
19-
20-
Optic can detect breaking changes between any two versions of an OpenAPI specification. Optic can lookup the versions using Git tags and branch names so you don't need to copy files around.
21-
22-
**Compares the HEAD to the `main` branch**
23-
```
24-
optic diff openapi.yml --base main --check
25-
```
26-
**Compares two branches by name**
27-
```
28-
optic diff feature/example:openapi.yml develop:main --check
29-
```
30-
**Compare files in against a remote URL**
31-
```
32-
optic diff --check \
33-
https://raw.githubusercontent.com/opticdev/bookstore-example/89c9a67935c850c1051059f4c719ef433dea8cc0/openapi.yml \
34-
https://raw.githubusercontent.com/opticdev/bookstore-example/ac5f3c55a6f7f27c482a557563686d0328dafb55/openapi.yml
35-
```
36-
37-
<img src="https://github.com/opticdev/optic/assets/5900338/fd6cdd7f-c147-467b-9517-84232baa898f" width="500" />
38-
39-
[Read Documentation](https://www.useoptic.com/docs/diff-openapi)
40-
41-
## Test the accuracy of your documentation using `optic capture`
42-
It can be difficult to keep an OpenAPI in-sync with your implementation. Optic tests if your OpenAPI is accurate by capturing traffic from your tests and comparing it to the spec.
43-
44-
Think of it like Snapshot testing, but for your API's behavior, with OpenAPI as the snapshot.
45-
46-
<details>
47-
<summary>Try it out with our example repo</summary>
48-
You can clone our example repo to try out `optic capture` against a repo that is already set up.
49-
50-
```bash
51-
git clone [email protected]:opticdev/examples.git
52-
cd ./examples/apps/bookstore-api
53-
npm install
54-
```
55-
56-
Once you've set up the repo, you can run `optic capture openapi.yml` to verify traffic against your OpenAPI spec, and `optic capture openapi.yml --update=interactive` to update any diffs.
57-
</details>
58-
59-
To start capturing your test traffic, run:
60-
61-
```
62-
optic capture init openapi.yml
63-
```
64-
65-
Configuration will be generated for you in the `optic.yml` file
66-
67-
```yml
68-
capture:
69-
openapi.yml:
70-
server:
71-
command: npm start # your server start command
72-
url: http://localhost:8080 # where your server starts
73-
requests:
74-
send:
75-
- path: /
76-
method: GET
77-
- path: /users/create
78-
method: POST
79-
headers:
80-
content-type: application/json;charset=UTF-8
81-
data:
82-
name: Hank
83-
```
84-
85-
Then you can run:
86-
87-
```
88-
optic capture openapi.yml
89-
```
90-
91-
<img width="602" alt="Screenshot 2023-09-08 at 2 11 00 PM" src="https://github.com/opticdev/optic/assets/18374483/a4daba2a-3be1-446d-9747-28a1cdce3926">
92-
93-
94-
When Optic detects a diff, you can correct it manually, or run `optic capture --update=interactive` to have Optic figures out exactly which lines of OpenAPI need to be updated and make the changes for you.
95-
96-
```
97-
optic capture openapi.yml --update=interactive
98-
```
99-
100-
<img width="604" alt="Screenshot 2023-09-08 at 2 12 15 PM" src="https://github.com/opticdev/optic/assets/18374483/c7c540c8-2501-4824-aac6-049587e29c0a">
101-
102-
103-
[Read Documentation](https://www.useoptic.com/docs/verify-openapi)
104-
105-
## Improve your API design with `optic diff`
106-
Optic is the first API linter built with the API lifecycle in-mind. When testing your API design, it always considers two versions of your API, for example: the version on the `develop` vs the `latest` release tag. This lets Optic check for all kinds of things [Spectral (and other liners) misses](https://www.useoptic.com/comparisons/spectral) like breaking changes and proper use of your API versioning scheme.
107-
108-
109-
<img src="https://github.com/opticdev/optic/assets/5900338/50a43d09-f531-405b-8b53-1c91ff5b8201" width="500" />
110-
111-
112-
Because Optic understands API change, it can apply your latest API standards to new API endpoints, and a looser set of standards to legacy endpoints that can’t change. [Teams like Snyk use Optic and this approach to govern all their APIs](https://snyk.io/blog/snyk-api-development-shift-left/). With Optic, developers only get actionable feedback from the tool and they don’t have to turn rules off to get CI to pass.
113-
114-
Create an `optic.yml` file in your repo and configure some of our built-in rules like using this template as a starting point:
115-
```yaml
116-
ruleset:
117-
# Prevent breaking changes
118-
- breaking-changes:
119-
# Pick an extension for your work-in-progress operations.
120-
# Breaking changes wil lbe allowed here
121-
exclude_operations_with_extension: x-draft
122-
# Run any existing spectral ruleset
123-
- spectral:
124-
# These rules will ony run on things you add to your API
125-
# Ie new properties, operations, responses, etc.
126-
added:
127-
# URLs are supported
128-
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
129-
# Local files work too.
130-
# - ./local-file.js
131-
# These rules will ony run on everything in the spec (normal spectral)
132-
always:
133-
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
134-
# Enforce consistent cases in your API
135-
- naming:
136-
# This will apply the rule to only new names (existing ones will be exempted)
137-
# Change to always if you want to fail on legacy names
138-
# Change to addedOrChanged if you want it to run on added or changed parts of the spec
139-
required_on: added
140-
# Different names for different parts of the spec
141-
# options = "snake_case" "camelCase" "Capital-Param-Case" "param-case" "PascalCase"
142-
requestHeaders: Capital-Param-Case
143-
responseHeaders: param-case
144-
properties: Capital-Param-Case
145-
pathComponents: param-case
146-
queryParameters: snake_case
147-
# Require your OpenAPI has examples, and that those examples match the schema
148-
- examples:
149-
# This will apply the rule to only new names (existing ones will be exempted)
150-
# Change to always if you want to fail on legacy names
151-
# Change to addedOrChanged if you want it to run on added or changed parts of the spec
152-
required_on: added
153-
# Turn on/off the parts of the spec that need examples
154-
require_request_examples: true
155-
require_response_examples: true
156-
require_parameter_examples: true
157-
# (optional) allow certain operations do not need examples
158-
exclude_operations_with_extension: x-legacy-api
159-
# Require documentation in your OpenAPI spec
160-
- documentation:
161-
# This will apply the rule to only new names (existing ones will be exempted)
162-
# Change to always if you want to fail on legacy names
163-
# Change to addedOrChanged if you want it to run on added or changed parts of the spec
164-
required_on: added
165-
require_property_descriptions: true
166-
require_operation_summary: true
167-
require_operation_description: true
168-
require_operation_id: true
169-
```
17016

171-
[Read documentation](https://www.useoptic.com/docs/style-guides)
17+
[Read Documentation](https://github.com/opticdev/optic/wiki)
17218

17319

174-
## Start running in CI
175-
To start using Optic in CI, [follow this guide](https://www.useoptic.com/docs/setup-ci). We provide template workflows for GitHub and GitLab to help you run Optic as a CI check:
176-
177-
### Github
178-
179-
```yaml
180-
# .github/workflows/optic.yml
181-
name: optic
182-
on:
183-
pull_request:
184-
push:
185-
branches:
186-
- "main"
187-
188-
jobs:
189-
run:
190-
runs-on: ubuntu-latest
191-
steps:
192-
- name: Checkout
193-
uses: actions/checkout@v3
194-
195-
- name: Install Optic
196-
run: npm install --location global @useoptic/optic
197-
198-
- name: Run Optic
199-
env:
200-
OPTIC_TOKEN: ${{ secrets.OPTIC_TOKEN }}
201-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
202-
run: optic run
203-
```
204-
205-
### Gitlab
206-
207-
Don't forget to add the `OPTIC_TOKEN` and `OPTIC_GITLAB_TOKEN` variables to your workflow.
208-
209-
```yaml
210-
# .gitlab-ci.yml
211-
optic-default-branch-push:
212-
image: node:latest
213-
rules:
214-
- if: $CI_PIPELINE_SOURCE == "push" && OPTIC_TOKEN && $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
215-
script:
216-
- npm install -g @useoptic/optic
217-
- optic run
218-
219-
optic-merge-request:
220-
image: node:latest
221-
rules:
222-
- if: $CI_PIPELINE_SOURCE == "merge_request_event" && $OPTIC_TOKEN
223-
script:
224-
- npm install -g @useoptic/optic
225-
- export OPTIC_RESULT=0; optic run || export OPTIC_RESULT=$?
226-
- if [ $OPTIC_RESULT -ne 0 ]; then exit 1; fi;
227-
```
228-
229-
230-
<img src="https://github.com/opticdev/optic/assets/5900338/18eb381a-59aa-42af-975a-36d1f24a5978" width="500" />
231-
23220
### License
23321
Optic is MIT Licensed
23422

235-
### Telemetry
236-
Optic collects telemetry which is used to help understand how to improve the product. For example, this usage data helps to debug issues and to prioritize features and improvements based on usage. The usage of our telemetry data falls under our [privacy policy](https://www.useoptic.com/privacy-policy). While this information does help us build a great product, we understand that not everyone wants to share their usage data. If you would like to disable telemetry you can add an environment variable that will opt out of sending usage data:
237-
238-
`OPTIC_TELEMETRY_LEVEL=off` - disables telemetry (both usage, and error reporting)
239-
`OPTIC_TELEMETRY_LEVEL=error` - disables telemetry (only usage data is sent)
23+
[Optic Labs is now part of Atlassian](https://www.atlassian.com/blog/announcements/optic-acquisition)

package.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,7 @@
99
"projects/openapi-utilities",
1010
"projects/rulesets-base",
1111
"projects/optic",
12-
"projects/standard-rulesets",
13-
"projects/fastify-capture"
12+
"projects/standard-rulesets"
1413
],
1514
"repository": {
1615
"type": "git",

projects/fastify-capture/README.md

Lines changed: 0 additions & 30 deletions
This file was deleted.

projects/fastify-capture/babel.config.js

Lines changed: 0 additions & 12 deletions
This file was deleted.

projects/fastify-capture/package.json

Lines changed: 0 additions & 45 deletions
This file was deleted.

0 commit comments

Comments
 (0)