From e040fdf9e408c22fc7129eeb97be5e2fc62d801e Mon Sep 17 00:00:00 2001 From: Aidan Cunniffe Date: Mon, 26 Aug 2024 11:09:58 -0400 Subject: [PATCH] Revert "Merge branch 'main' into pkg-snapshot-dirname" This reverts commit 699981d3e714b9a1b92950bcd3a7aafabf24d2c7, reversing changes made to a2fdd15cb684dbf3c5474a24b2aaaaf8a2acb0b1. --- README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1cf222be25..afbc5ac212 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ https://raw.githubusercontent.com/opticdev/bookstore-example/ac5f3c55a6f7f27c482 +[Read Documentation](https://www.useoptic.com/docs/diff-openapi) ## Test the accuracy of your documentation using `optic capture` 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. @@ -104,9 +105,10 @@ optic capture openapi.yml --update=interactive Screenshot 2023-09-08 at 2 12 15 PM +[Read Documentation](https://www.useoptic.com/docs/verify-openapi) ## Improve your API design with `optic diff` -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 like breaking changes and proper use of your API versioning scheme. +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. @@ -171,6 +173,73 @@ ruleset: require_operation_id: true ``` +[Read documentation](https://www.useoptic.com/docs/style-guides) + + +## Start running in CI +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: + +### Github + +```yaml +# .github/workflows/optic.yml +name: optic +on: + pull_request: + push: + branches: + - "main" + +jobs: + run: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Install Optic + run: npm install --location global @useoptic/optic + + - name: Run Optic + env: + OPTIC_TOKEN: ${{ secrets.OPTIC_TOKEN }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: optic run +``` + +### Gitlab + +Don't forget to add the `OPTIC_TOKEN` and `OPTIC_GITLAB_TOKEN` variables to your workflow. + +```yaml +# .gitlab-ci.yml +optic-default-branch-push: + image: node:latest + rules: + - if: $CI_PIPELINE_SOURCE == "push" && OPTIC_TOKEN && $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH + script: + - npm install -g @useoptic/optic + - optic run + +optic-merge-request: + image: node:latest + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $OPTIC_TOKEN + script: + - npm install -g @useoptic/optic + - export OPTIC_RESULT=0; optic run || export OPTIC_RESULT=$? + - if [ $OPTIC_RESULT -ne 0 ]; then exit 1; fi; +``` + + + + + +## Resources +- [Read our full documentation here](https://www.useoptic.com/docs) +- [Need help? Book office hours](https://calendly.com/optic-onboarding/optic-office-hours) +- [Join us on Discord](https://discord.com/invite/t9hADkuYjP) + ### License Optic is MIT Licensed