docs: add swagger protection docs (#791)

Co-authored-by: Ran Isenberg <ran.isenberg@ranthebuilder.cloud>

Author: ran-isenberg

README.md

@@ -94,6 +94,7 @@ This project aims to reduce cognitive load and answer these questions for you by
 - CloudWatch dashboards - High level and low level including CloudWatch alarms
 - Unit, infrastructure, security, integration and end to end tests.
 - Automatically generated OpenAPI endpoint: /swagger with Pydnatic schemas for both requests and responses
+- CI swagger protection - fails the PR if your swagger JSON file (stored at docs/swagger/openapi.json) is out of date
 
 
 ## CDK Deployment

docs/getting_started.md

@@ -68,14 +68,18 @@ CDK destroy can be run with ``make destroy``.
 
 ## **Preparing Code for PR**
 
-Run ``make pr``. This command will run all the required checks, pre commit hooks, linters, code formatters, import sorting and tests, so you can be sure GitHub's pipeline will pass.
+Run ``make pr``. This command will run all the required checks, pre commit hooks, linters, code formatters, import sorting and tests, so you can be sure GitHub's pipeline will pass. It will also generate an updated swagger OpenAPI JSON file and place it at docs/swagger/openapi.json location.
 
 The command auto fixes errors in the code for you.
 
 If there's an error in the pre-commit stage, it gets auto fixed. However, are required to run ``make pr`` again so it continues to the next stages.
 
 Be sure to commit all the changes that ``make pr`` does for you.
 
+## **OpenAPI Swagger Generation**
+Run either ``make pr`` or ``make openopi`` to generate an updated swagger OpenAPI JSON file and place it at docs/swagger/openapi.json location.
+
+
 ## **GitHub Pages Documentation**
 
 ``make docs`` can be run to start a local HTTP server with the project's documentation pages.

docs/pipeline.md

@@ -28,8 +28,10 @@ All steps can be run locally using the makefile. See details below:
 - Infrastructure test. Run `make infra-tests` to run the CDK infrastructure tests in the IDE
 - Code coverage by [codecov.io](https://about.codecov.io/)
 - Deploy CDK - run `make deploy` in the IDE, will also run security tests based on cdk_nag
+- Integration tests - run `make integration` in the IDE.
 - E2E tests  - run `make e2e` in the IDE
 - Code coverage tests  - run `make coverage-tests` in the IDE after CDK dep
+- OpenAPI Swagger file - run
 - Update GitHub documentation branch
 
 ### **Other Capabilities**
@@ -49,11 +51,11 @@ The two most important ones are `pr-serverless-service`  and `main-serverless-se
 
 <img alt="alt_text" src="../media/cicd_pr.png" />
 
-`pr-serverless-service` runs for every pull request you open. It expects you defined a GitHub environment by the name `dev` and that it includes a secret by the name of `AWS_ROLE`.
+`pr-serverless-service` runs for every pull request you open. It expects you defined a GitHub environments by the name `dev`, `staging` and `production` and for each environments to have the following variables:  `CODECOV_TOKEN ` for CodeCov integration and `AWS_ROLE` that allows GitHub to deploy to that AWS account (one for dev, one for staging and one for production accounts).
 
 It includes two jobs: 'quality_standards' and 'tests' where a failure in 'quality_standards' does not trigger 'tests'. Both jobs MUST pass in order to to be able to merge.
 
-'quality_standards' includes all linters, pre-commit checks and units tests and 'tests' deploys the service to AWS, runs code coverage checks, security checks and E2E tests. Stack is destroyed at the end. Stack has a 'dev' prefix as part of its name.
+'quality_standards' includes all linters, pre-commit checks and units tests and 'tests' deploys the service to AWS, runs code coverage checks, checks that your OpenAPI file is up to date and corresponds to the actual deployment (fails if it does not, hence your documentation is out of date), security checks and E2E tests. Stack is destroyed at the end. Stack has a 'dev' prefix as part of its name. Each environment has a pre-defined stack prefix.
 
 Once merged, `main-serverless-service` will run.