-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #10 from opticdev/feat/ci/add_workflow_dispatch
feat(ci): add workflow_dispatch to bookstore example
- Loading branch information
Showing
9 changed files
with
27 additions
and
381 deletions.
There are no files selected for viewing
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,65 +1,26 @@ | ||
name: bookstore-api-optic | ||
name: optic | ||
on: | ||
pull_request: | ||
push: | ||
branches: | ||
- main | ||
paths: | ||
- apps/bookstore-api/** | ||
pull_request: | ||
paths: | ||
- apps/bookstore-api/** | ||
workflow_call: | ||
|
||
defaults: | ||
run: | ||
working-directory: apps/bookstore-api | ||
run: | ||
working-directory: apps/bookstore-api | ||
|
||
jobs: | ||
diff-all: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Checkout | ||
uses: actions/checkout@v3 | ||
|
||
- name: Install dependencies | ||
run: yarn install | ||
|
||
- name: Generate Spec | ||
run: yarn generate-spec | ||
|
||
- uses: opticdev/action@v1 | ||
with: | ||
# Your Optic Cloud Token | ||
optic_token: ${{ secrets.OPTIC_TOKEN }} | ||
|
||
# A GitHub token with access to create comments on pull requests | ||
github_token: ${{ secrets.GITHUB_TOKEN }} | ||
|
||
# If true, standard check failures will cause this action to fail. | ||
# If false, standard check failures will show in PR comments and | ||
# in Optic Cloud but will not cause the action to fail | ||
standards_fail: true | ||
|
||
# If you have more than one spec, separate matches with commas | ||
# (openapi.yml,other.yml) | ||
additional_args: --match apps/bookstore-api/openapi.yml | ||
|
||
compare_from_pr: cloud:default | ||
compare_from_push: cloud:default | ||
verify: | ||
run: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Checkout | ||
uses: actions/checkout@v3 | ||
|
||
- name: Install dependencies | ||
run: yarn install | ||
|
||
- name: Install Optic | ||
run: sh -c "$(curl -Ls https://install.useoptic.com/install.sh)" -- latest /usr/local/bin/ | ||
|
||
- name: Generate Spec | ||
run: yarn generate-spec | ||
run: npm install --location global @useoptic/optic | ||
|
||
- name: Verify spec against integration tests | ||
run: yarn verify | ||
- name: Run Optic | ||
env: | ||
OPTIC_TOKEN: ${{ secrets.OPTIC_TOKEN }} | ||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
run: optic run |
This file was deleted.
Oops, something went wrong.
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,50 +1,16 @@ | ||
# Bookstore API | ||
|
||
Bookstore API built using Fastify and Typescript with Optic. Generates an OpenAPI spec using `@fastify/swagger` and tracks changes using Optic. We have set up Optic to: | ||
- [preview API changes in PRs](#preview-api-changes-in-prs) | ||
- [test for breaking changes](https://github.com/opticdev/bookstore-api/pull/1) | ||
- [enforce the API style guide](https://github.com/opticdev/bookstore-api/pull/3) | ||
- [share our API changelog and documentation with consumers](#accurate-documentation-and-changelogs) | ||
|
||
Take a look at the guides or just dig around the repo. You can start a server or generate an OpenAPI spec from the code. | ||
|
||
## Running this repo locally | ||
|
||
To run this locally, you will need [node >= 16](https://nodejs.org/en) and [yarn](https://yarnpkg.com/getting-started/install). | ||
|
||
Get started by installing dependencies: | ||
|
||
`yarn install` | ||
|
||
And then run one of the following commands: | ||
- `yarn start:local` - starts the server | ||
- `yarn verify` - verifies the spec using integration tests | ||
- `yarn generate-spec` - generates an OpenAPI spec from code definitions | ||
|
||
## Preview API changes in PRs | ||
|
||
Take a look at the [open pull requests of the repo](https://github.com/opticdev/bookstore-api/pulls). It's difficult to know how the code changes will impact your API. Optic adds preview documentation and an API changelog to each PR so every developer on your team knows exactly what changes to the API have been proposed. | ||
|
||
Here are a couple of examples of what Optic can do: | ||
- [Optic caught a breaking change](https://github.com/opticdev/bookstore-api/pull/1) | ||
- A small line of code can change multiple endpoints. [Optic makes it easy to see the effective API changes being proposed](https://github.com/opticdev/bookstore-api/pull/2) | ||
- [Adding 2 new query parameters that do not follow our team's naming conventions](https://github.com/opticdev/bookstore-api/pull/3) | ||
|
||
## Accurate documentation and changelogs | ||
|
||
Every time this repositories main branch is updated, a new version of your API is pushed to Optic. Developers on your team, or your consumers (if public), can see a complete API changelog, and accurate documentation for the API. | ||
|
||
- [View the Optic Changelog](https://app.useoptic.com/organizations/32613bcd-704e-4661-85f0-7b3d75613fb0/apis/Ru2Me4G-2nIro-cj4Bbib) | ||
![optic changelog](/images/changelog.png) | ||
- [View diffs between different API versions](https://app.useoptic.com/organizations/32613bcd-704e-4661-85f0-7b3d75613fb0/apis/Ru2Me4G-2nIro-cj4Bbib/operations/get.%2Fauthors%2F%7BauthorId%7D?diffTag=fyXT_OAvfLfjlipBFl2Xw) | ||
![diff two versions](/images/diff-versions.png) | ||
- [Preview documentation and changes in pull requests](https://github.com/opticdev/bookstore-api/pull/2#issuecomment-1613615164) | ||
![preview changes](/images/preview-changes.png) | ||
|
||
You can also add badges to your repository that show you how often your API is changing and the number of endpoints you have. | ||
|
||
[![Optic badge of documentation](https://app.useoptic.com/organizations/32613bcd-704e-4661-85f0-7b3d75613fb0/public/apis/Ru2Me4G-2nIro-cj4Bbib/badge.svg?type=documentation&code=O3UVmk3goSaVOxxbSTHxu.hiMaTkrqNRj8dEb41awZRxdn0iUZ9UhT)](https://app.useoptic.com/organizations/32613bcd-704e-4661-85f0-7b3d75613fb0/apis/Ru2Me4G-2nIro-cj4Bbib?ref=badge) [![Optic badge of changes](https://app.useoptic.com/organizations/32613bcd-704e-4661-85f0-7b3d75613fb0/public/apis/Ru2Me4G-2nIro-cj4Bbib/badge.svg?type=changes&code=a5dN_bRR7n6-MEutVOj8f.jdaniuNKGOz-CgAf_R5YfQIR3UvNYcWK)](https://app.useoptic.com/organizations/32613bcd-704e-4661-85f0-7b3d75613fb0/apis/Ru2Me4G-2nIro-cj4Bbib?ref=badge) | ||
|
||
## Set up Optic Cloud | ||
|
||
You can follow instructions on how to set up Optic Cloud on [our website](https://www.useoptic.com/docs/cloud-get-started). If you generate an OpenAPI spec from your code (just like this repo), you should follow our [generated spec set up guide](https://www.useoptic.com/docs/setup-ci-generated). | ||
A demo repository with a book store API example. | ||
|
||
## Local usage | ||
- Run `optic run` on the main branch | ||
- make some changes to `openapi.yml` | ||
- run `optic run` again. | ||
|
||
## CI setup | ||
The repo is setup with Gitlab CI and Github Action configuration files: | ||
- fork the repository | ||
- grab an Optic organization token from https://app.useoptic.com `tokens` tab, and set it as `OPTIC_TOKEN` in your CI env | ||
- add a `GITHUB_TOKEN` or `OPTIC_GITLAB_TOKEN` with comment permission to your CI env (more about this [in the docs](http://localhost:3000/docs/setup-ci#configure-commenting-on-pull-requests-optional)) | ||
- create a pull request containing breaking changes in `openapi.yml` to see Optic in action. | ||
|
||
## Advanced | ||
- Configure custom governance rules in `optic.yml`: read [the docs](http://localhost:3000/docs/lint-openapi) |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.