From a930a63355c5b2416d230b7984bba79b33ef3ba6 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 23 Oct 2024 10:49:56 +0100 Subject: [PATCH 1/9] NPA-3332 Run Prettier and Update top headers --- README.md | 91 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 53 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 647fb0f..6604204 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,24 @@ # validated-relationships-service-api -![Build](https://github.com/NHSDigital/validated-relationships-service-api/workflows/Build/badge.svg?branch=master) +This is a RESTful API for the Validated Relationship Service (VRS) API. -This is a specification for the *validated-relationships-service-api* API. +It includes: +- `specification/` This [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers. +- `sandbox/` A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing. +- `scripts/` Utilities helpful to developers of this specification. +- `proxies/` Live (connecting to another service) and sandbox (using the sandbox container) Apigee API Proxy definitions. -* `specification/` This [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers. -* `sandbox/` A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing. -* `scripts/` Utilities helpful to developers of this specification. -* `proxies/` Live (connecting to another service) and sandbox (using the sandbox container) Apigee API Proxy definitions. +Consumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service). -Consumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://digital.nhs.uk/developer). +This repo does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Core Spine' which is not currently open source. ## Contributing + Contributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](https://github.com/NHSDigital/validated-relationships-service-api/blob/master/CONTRIBUTING.md) and the [community code of conduct](https://github.com/NHSDigital/validated-relationships-service-api/blob/master/CODE_OF_CONDUCT.md). ### Licensing + This code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses. The contents of this repository are protected by Crown Copyright (C). @@ -23,17 +26,20 @@ The contents of this repository are protected by Crown Copyright (C). ## Development ### Requirements -* make -* nodejs + npm/yarn -* Python 3.8 + [poetry](https://github.com/python-poetry/poetry) -* Java 8+ + +- make +- nodejs + npm/yarn +- Python 3.8 + [poetry](https://github.com/python-poetry/poetry) +- Java 8+ ### Install + ``` $ make install ``` #### Updating hooks + You can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run in CI, but it's useful to run them locally too. @@ -42,60 +48,66 @@ $ make install ``` ### Environment Variables + Various scripts and commands rely on environment variables being set. These are documented with the commands. :bulb: Consider using [direnv](https://direnv.net/) to manage your environment variables during development and maintaining your own `.envrc` file - the values of these variables will be specific to you and/or sensitive. ### Make commands + There are `make` commands that alias some of this functionality: - * `lint` -- Lints the spec and code - * `publish` -- Outputs the specification as a **single file** into the `build/` directory - * `serve` -- Serves a preview of the specification in human-readable format + +- `lint` -- Lints the spec and code +- `publish` -- Outputs the specification as a **single file** into the `build/` directory +- `serve` -- Serves a preview of the specification in human-readable format ### Testing + Each API and team is unique. We encourage you to use a `test/` folder in the root of the project, and use whatever testing frameworks or apps your team feels comfortable with. It is important that the URL your test points to be configurable. We have included some stubs in the Makefile for running tests. ### VS Code Plugins - * [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command - * [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation - +- [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command +- [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation ### Emacs Plugins - * [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help +- [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help ### Speccy -> [Speccy](http://speccy.io/) *A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution.* +> [Speccy](http://speccy.io/) _A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution._ Speccy does the lifting for the following npm scripts: - * `test` -- Lints the definition - * `publish` -- Outputs the specification as a **single file** into the `build/` directory - * `serve` -- Serves a preview of the specification in human-readable format +- `test` -- Lints the definition +- `publish` -- Outputs the specification as a **single file** into the `build/` directory +- `serve` -- Serves a preview of the specification in human-readable format -(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the *developerjack* blog.) +(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the _developerjack_ blog.) :bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file. ### Caveats #### Swagger UI + Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead. #### Apigee Portal + The Apigee portal will not automatically pull examples from schemas, you must specify them manually. ### Platform setup As currently defined in your `proxies` folder, your proxies do pretty much nothing. -Telling Apigee how to connect to your backend requires a *Target Server*, which you should call named `validated-relationships-service-api-target`. -Our *Target Servers* defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure) repository. +Telling Apigee how to connect to your backend requires a _Target Server_, which you should call named `validated-relationships-service-api-target`. +Our _Target Servers_ defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure) repository. :bulb: For Sandbox-running environments (`test`) these need to be present for successful deployment but can be set to empty/dummy values. ### Detailed folder walk through + To get started developing your API use this template repo alongside guidance provided by the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Deliver+your+API) #### `/.github`: @@ -103,18 +115,20 @@ To get started developing your API use this template repo alongside guidance pro This folder contains templates that can be customised for items such as opening pull requests or issues within the repo `/.github/workflows`: This folder contains templates for GitHub action workflows such as: -- `pr-lint.yaml`: This workflow template shows how to link Pull Request's to Jira tickets and runs when a pull request is opened. -- `continuous-integration.yml`: This workflow template shows how to publish a Github release when pushing to master. -- `sandbox-checks.yaml`: This workflow checks the sandbox meets the formatting and linting rules (Black + Flake8). Also it runs the sandbox unit tests (Pytest) -- `dependency-review.yml`: This workflow checks for any vulnerabilities in dependencies to be added to the project. -- `codeql-analysis.yml`: This workflow checks for any code vulnerabilities in the project. + +- `pr-lint.yaml`: This workflow template shows how to link Pull Request's to Jira tickets and runs when a pull request is opened. +- `continuous-integration.yml`: This workflow template shows how to publish a Github release when pushing to master. +- `sandbox-checks.yaml`: This workflow checks the sandbox meets the formatting and linting rules (Black + Flake8). Also it runs the sandbox unit tests (Pytest) +- `dependency-review.yml`: This workflow checks for any vulnerabilities in dependencies to be added to the project. +- `codeql-analysis.yml`: This workflow checks for any code vulnerabilities in the project. #### `/azure`: Contains templates defining Azure Devops pipelines. By default the following pipelines are available: -- `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. By default this pipeline is enabled for all branches. -- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. You can run automated and manual tests against these while you develop. By default this pipeline will deploy to internal-dev, but the template can be amended to add other environments as required. -- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master. + +- `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. By default this pipeline is enabled for all branches. +- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. You can run automated and manual tests against these while you develop. By default this pipeline will deploy to internal-dev, but the template can be amended to add other environments as required. +- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master. The `project.yml` file needs to be populated with your service names to make them available to the pipelines @@ -128,8 +142,8 @@ There are 2 folders `/live` and `/sandbox` allowing you to define a different pr Within the `live/apiproxy` and `sandbox/apiproxy` folders are: -`/proxies/default.xml`: Defines the proxy's Flows. Flows define how the proxy should handle different requests. By default, _ping and _status endpoint flows are defined. -See the APM confluence for more information on how the [_ping](https://nhsd-confluence.digital.nhs.uk/display/APM/_ping+endpoint) and [_status](https://nhsd-confluence.digital.nhs.uk/display/APM/_status+endpoint) endpoints work. +`/proxies/default.xml`: Defines the proxy's Flows. Flows define how the proxy should handle different requests. By default, \_ping and \_status endpoint flows are defined. +See the APM confluence for more information on how the [\_ping](https://nhsd-confluence.digital.nhs.uk/display/APM/_ping+endpoint) and [\_status](https://nhsd-confluence.digital.nhs.uk/display/APM/_status+endpoint) endpoints work. `/policies`: Populated with a set of standard XML Apigee policies that can be used in flows. @@ -155,9 +169,10 @@ Create an OpenAPI Specification to document your API. For more information about #### `/tests`: -End to End tests. These tests are written in Python and use the PyTest test runner. Before running these tests you will need to set environment variables. The `test_endpoint.py` file provides a template of how to set up tests which test your api endpoints. For more information about testing your API see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Testing+your+API ). +End to End tests. These tests are written in Python and use the PyTest test runner. Before running these tests you will need to set environment variables. The `test_endpoint.py` file provides a template of how to set up tests which test your api endpoints. For more information about testing your API see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Testing+your+API). #### `Makefile`: + Useful make targets to get started including: installing dependencies and running smoke tests. #### `ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`: @@ -168,11 +183,11 @@ These files are required to deploy containers alongside your Apigee proxy during `ecs-proxies-deploy.yml` : Here you can define config for your container deployment. -For more information about deploying ECS containers see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Developing+ECS+proxies#DevelopingECSproxies-Buildingandpushingdockercontainers ). +For more information about deploying ECS containers see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Developing+ECS+proxies#DevelopingECSproxies-Buildingandpushingdockercontainers). #### `manifest_template.yml`: -This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Manifest.yml+reference ). +This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Manifest.yml+reference). #### Package management: From ec7a9d7b32d47f996484dda6c8c01f967dca8595 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 23 Oct 2024 10:59:59 +0100 Subject: [PATCH 2/9] NPA-3332 Continue rewording project description --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6604204..92da057 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # validated-relationships-service-api -This is a RESTful API for the Validated Relationship Service (VRS) API. +This is a RESTful FHIR API for the [Validated Relationship Service API](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service). It includes: @@ -11,7 +11,7 @@ It includes: Consumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service). -This repo does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Core Spine' which is not currently open source. +This repository does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Proxy Validated Relationship Service' repository which is not currently open source. ## Contributing From 53ee414d792932f49509341ec66c6386d1bf470e Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 23 Oct 2024 11:07:05 +0100 Subject: [PATCH 3/9] NPA-3332 Begin move of development parts of the readme to DEVELOPMENT_GUIDE.md --- CONTRIBUTING.md | 30 +++++++++++++-- DEVELOPMENT_GUIDE.md | 79 ++++++++++++++++++++++++++++++++++++++ README.md | 90 +++++++++++++------------------------------- 3 files changed, 131 insertions(+), 68 deletions(-) create mode 100644 DEVELOPMENT_GUIDE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a6dab7..bbdb7fe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,29 @@ # Contribution Guidelines +- [Contribution Guidelines](#contribution-guidelines) + - [Raising an Issue](#raising-an-issue) + - [Contributing code](#contributing-code) + - [Merge responsibility](#merge-responsibility) + - [Branch naming](#branch-naming) + - [Commit messages](#commit-messages) + - [Development](#development) + - [Requirements](#requirements) + - [Install](#install) + - [Updating hooks](#updating-hooks) + - [Environment Variables](#environment-variables) + - [Make commands](#make-commands) + - [Testing](#testing) + - [VS Code Plugins](#vs-code-plugins) + - [Emacs Plugins](#emacs-plugins) + - [Speccy](#speccy) + ## Raising an Issue + If you raise an issue against this repository, please include as much information as possible to reproduce any bugs, or specific locations in the case of content errors. ## Contributing code + To contribute code, please fork the repository and raise a pull request. Ideally pull requests should be fairly granular and aim to solve one problem each. It would also be helpful if they @@ -12,11 +31,13 @@ linked to an issue. If the maintainers cannot understand why a pull request was so please explain why the changes need to be made (unless it is self-evident). ### Merge responsibility -* It is the responsibility of the reviewer to merge branches they have approved. -* It is the responsibility of the author of the merge to ensure their merge is in a mergeable state. -* It is the responsibility of the maintainers to ensure the merge process is unambiguous and automated where possible. + +- It is the responsibility of the reviewer to merge branches they have approved. +- It is the responsibility of the author of the merge to ensure their merge is in a mergeable state. +- It is the responsibility of the maintainers to ensure the merge process is unambiguous and automated where possible. ### Branch naming + Branch names should be of the format: `apm-nnn-short-issue-description` @@ -24,11 +45,12 @@ Branch names should be of the format: Multiple branches are permitted for the same ticket. ### Commit messages + Commit messages should be formatted as follows: + ``` APM-NNN Summary of changes Longer description of changes if explaining rationale is necessary, limited to 80 columns and spanning as many lines as you need. ``` - diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md new file mode 100644 index 0000000..8d297d0 --- /dev/null +++ b/DEVELOPMENT_GUIDE.md @@ -0,0 +1,79 @@ +# Development Guide + + +- [Development Guide](#development-guide) + - [Development](#development) + - [Requirements](#requirements) + - [Install](#install) + - [Updating hooks](#updating-hooks) + - [Environment Variables](#environment-variables) + - [Make commands](#make-commands) + - [Testing](#testing) + - [VS Code Plugins](#vs-code-plugins) + - [Emacs Plugins](#emacs-plugins) + - [Speccy](#speccy) + +## Development + +### Requirements + +- make +- nodejs + npm/yarn +- Python 3.8 + [poetry](https://github.com/python-poetry/poetry) +- Java 8+ + +### Install + +``` +$ make install +``` + +#### Updating hooks + +You can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run +in CI, but it's useful to run them locally too. + +``` +$ make install +``` + +### Environment Variables + +Various scripts and commands rely on environment variables being set. These are documented with the commands. + +:bulb: Consider using [direnv](https://direnv.net/) to manage your environment variables during development and maintaining your own `.envrc` file - the values of these variables will be specific to you and/or sensitive. + +### Make commands + +There are `make` commands that alias some of this functionality: + +- `lint` -- Lints the spec and code +- `publish` -- Outputs the specification as a **single file** into the `build/` directory +- `serve` -- Serves a preview of the specification in human-readable format + +### Testing + +Each API and team is unique. We encourage you to use a `test/` folder in the root of the project, and use whatever testing frameworks or apps your team feels comfortable with. It is important that the URL your test points to be configurable. We have included some stubs in the Makefile for running tests. + +### VS Code Plugins + +- [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command +- [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation + +### Emacs Plugins + +- [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help + +### Speccy + +> [Speccy](http://speccy.io/) _A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution._ + +Speccy does the lifting for the following npm scripts: + +- `test` -- Lints the definition +- `publish` -- Outputs the specification as a **single file** into the `build/` directory +- `serve` -- Serves a preview of the specification in human-readable format + +(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the _developerjack_ blog.) + +:bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file. diff --git a/README.md b/README.md index 92da057..95726ce 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,32 @@ Consumers of the API will find developer documentation on the [NHS Digital Devel This repository does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Proxy Validated Relationship Service' repository which is not currently open source. +- [validated-relationships-service-api](#validated-relationships-service-api) + - [Contributing](#contributing) + - [Licensing](#licensing) + - [Development \& Testing](#development--testing) + - [Caveats](#caveats) + - [Swagger UI](#swagger-ui) + - [Apigee Portal](#apigee-portal) + - [Platform setup](#platform-setup) + - [Detailed folder walk through](#detailed-folder-walk-through) + - [`/.github`:](#github) + - [`/azure`:](#azure) + - [`/proxies`:](#proxies) + - [`/sandbox`:](#sandbox) + - [Development](#development) + - [`/scripts`:](#scripts) + - [`/specification`:](#specification) + - [`/tests`:](#tests) + - [`Makefile`:](#makefile) + - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) + - [`manifest_template.yml`:](#manifest_templateyml) + - [Package management:](#package-management) + + ## Contributing -Contributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](https://github.com/NHSDigital/validated-relationships-service-api/blob/master/CONTRIBUTING.md) and the [community code of conduct](https://github.com/NHSDigital/validated-relationships-service-api/blob/master/CODE_OF_CONDUCT.md). +Contributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](./CONTRIBUTING.md) and the [community code of conduct](./CODE_OF_CONDUCT.md). ### Licensing @@ -23,70 +46,9 @@ This code is dual licensed under the MIT license and the OGL (Open Government Li The contents of this repository are protected by Crown Copyright (C). -## Development - -### Requirements - -- make -- nodejs + npm/yarn -- Python 3.8 + [poetry](https://github.com/python-poetry/poetry) -- Java 8+ - -### Install - -``` -$ make install -``` - -#### Updating hooks - -You can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run -in CI, but it's useful to run them locally too. - -``` -$ make install -``` - -### Environment Variables - -Various scripts and commands rely on environment variables being set. These are documented with the commands. - -:bulb: Consider using [direnv](https://direnv.net/) to manage your environment variables during development and maintaining your own `.envrc` file - the values of these variables will be specific to you and/or sensitive. - -### Make commands - -There are `make` commands that alias some of this functionality: - -- `lint` -- Lints the spec and code -- `publish` -- Outputs the specification as a **single file** into the `build/` directory -- `serve` -- Serves a preview of the specification in human-readable format - -### Testing - -Each API and team is unique. We encourage you to use a `test/` folder in the root of the project, and use whatever testing frameworks or apps your team feels comfortable with. It is important that the URL your test points to be configurable. We have included some stubs in the Makefile for running tests. - -### VS Code Plugins - -- [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command -- [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation - -### Emacs Plugins - -- [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help - -### Speccy - -> [Speccy](http://speccy.io/) _A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution._ - -Speccy does the lifting for the following npm scripts: - -- `test` -- Lints the definition -- `publish` -- Outputs the specification as a **single file** into the `build/` directory -- `serve` -- Serves a preview of the specification in human-readable format - -(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the _developerjack_ blog.) +## Development & Testing -:bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file. +All development commands and documentation can be found in the [DEVELOPMENT_GUIDE.md](./CONTRIBUTING.md) file. ### Caveats From 01c9f5791e61dec65fbc54b7bcdd8e5622e0ddec Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 23 Oct 2024 11:23:55 +0100 Subject: [PATCH 4/9] NPA-3332 Complete move of development parts of the readme to DEVELOPMENT_GUIDE.md --- DEVELOPMENT_GUIDE.md | 126 ++++++++++++++++++++++++++++++++++- README.md | 152 +++++-------------------------------------- 2 files changed, 140 insertions(+), 138 deletions(-) diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md index 8d297d0..045f3f4 100644 --- a/DEVELOPMENT_GUIDE.md +++ b/DEVELOPMENT_GUIDE.md @@ -12,12 +12,29 @@ - [VS Code Plugins](#vs-code-plugins) - [Emacs Plugins](#emacs-plugins) - [Speccy](#speccy) + - [Caveats](#caveats) + - [Swagger UI](#swagger-ui) + - [Apigee Portal](#apigee-portal) + - [Platform setup](#platform-setup) + - [Detailed folder walk through](#detailed-folder-walk-through) + - [`/.github`:](#github) + - [`/azure`:](#azure) + - [`/proxies`:](#proxies) + - [`/sandbox`:](#sandbox) + - [Development](#development-1) + - [`/scripts`:](#scripts) + - [`/specification`:](#specification) + - [`/tests`:](#tests) + - [`Makefile`:](#makefile) + - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) + - [`manifest_template.yml`:](#manifest_templateyml) + - [Package management:](#package-management) ## Development ### Requirements -- make +- GNU make - nodejs + npm/yarn - Python 3.8 + [poetry](https://github.com/python-poetry/poetry) - Java 8+ @@ -77,3 +94,110 @@ Speccy does the lifting for the following npm scripts: (Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the _developerjack_ blog.) :bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file. + +### Caveats + +#### Swagger UI + +Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead. + +#### Apigee Portal + +The Apigee portal will not automatically pull examples from schemas, you must specify them manually. + +### Platform setup + +As currently defined in your `proxies` folder, your proxies do pretty much nothing. +Telling Apigee how to connect to your backend requires a _Target Server_, which you should call named `validated-relationships-service-api-target`. +Our _Target Servers_ defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure) repository. + +:bulb: For Sandbox-running environments (`test`) these need to be present for successful deployment but can be set to empty/dummy values. + +### Detailed folder walk through + +To get started developing your API use this template repo alongside guidance provided by the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Deliver+your+API) + +#### `/.github`: + +This folder contains templates that can be customised for items such as opening pull requests or issues within the repo + +`/.github/workflows`: This folder contains templates for GitHub action workflows such as: + +- `pr-lint.yaml`: This workflow template shows how to link Pull Request's to Jira tickets and runs when a pull request is opened. +- `continuous-integration.yml`: This workflow template shows how to publish a Github release when pushing to master. +- `sandbox-checks.yaml`: This workflow checks the sandbox meets the formatting and linting rules (Black + Flake8). Also it runs the sandbox unit tests (Pytest) +- `dependency-review.yml`: This workflow checks for any vulnerabilities in dependencies to be added to the project. +- `codeql-analysis.yml`: This workflow checks for any code vulnerabilities in the project. + +#### `/azure`: + +Contains templates defining Azure Devops pipelines. By default the following pipelines are available: + +- `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. By default this pipeline is enabled for all branches. +- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. You can run automated and manual tests against these while you develop. By default this pipeline will deploy to internal-dev, but the template can be amended to add other environments as required. +- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master. + +The `project.yml` file needs to be populated with your service names to make them available to the pipelines + +`/azure/templates`: Here you can define reusable actions, such as running tests, and call these actions during Azure Devops pipelines. + +#### `/proxies`: + +This folder contains files relating to your Apigee API proxy. + +There are 2 folders `/live` and `/sandbox` allowing you to define a different proxy for sandbox use. By default, this sandbox proxy is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo) + +Within the `live/apiproxy` and `sandbox/apiproxy` folders are: + +`/proxies/default.xml`: Defines the proxy's Flows. Flows define how the proxy should handle different requests. By default, \_ping and \_status endpoint flows are defined. +See the APM confluence for more information on how the [\_ping](https://nhsd-confluence.digital.nhs.uk/display/APM/_ping+endpoint) and [\_status](https://nhsd-confluence.digital.nhs.uk/display/APM/_status+endpoint) endpoints work. + +`/policies`: Populated with a set of standard XML Apigee policies that can be used in flows. + +`/resources/jsc`: Snippets of javascript code that are used in Apigee Javascript policies. For more info about Javascript policies see [here](https://docs.apigee.com/api-platform/reference/policies/javascript-policy) + +`/targets`: The XMLs within these folders set up target definitions which allow connections to external target servers. The sandbox target definition is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo). For more info on setting up a target server see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Setting+up+a+target+server) + +#### `/sandbox`: + +Sandbox provides a API for exploring the Proxy API. It uses pre-canned responses to most common scenarios. + +##### Development + +For information on how to develop the sandbox API see [README.md](sandbox/README.md) + +#### `/scripts`: + +Contains useful scripts that are used throughout the project, for example in Makefile and Github workflows + +#### `/specification`: + +Create an OpenAPI Specification to document your API. For more information about developing specifications see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Documenting+your+API). + +#### `/tests`: + +End to End tests. These tests are written in Python and use the PyTest test runner. Before running these tests you will need to set environment variables. The `test_endpoint.py` file provides a template of how to set up tests which test your api endpoints. For more information about testing your API see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Testing+your+API). + +#### `Makefile`: + +Useful make targets to get started including: installing dependencies and running smoke tests. + +#### `ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`: + +These files are required to deploy containers alongside your Apigee proxy during the Azure Devops `azure-build-pipeline`. In this template repo we are deploying our sandbox container which is used as the target server for the sandbox proxy. + +`ecs-proxies-containers.yml`: The path to a container's Dockerfile is defined here. This path needs to be defined to allow containers to be pushed to our repository during the `azure-build-pipeline`. + +`ecs-proxies-deploy.yml` : Here you can define config for your container deployment. + +For more information about deploying ECS containers see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Developing+ECS+proxies#DevelopingECSproxies-Buildingandpushingdockercontainers). + +#### `manifest_template.yml`: + +This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Manifest.yml+reference). + +#### Package management: + +This template uses poetry for python dependency management, and uses these files: poetry.lock, poetry.toml, pyproject.toml. + +Node dependencies of this template project and some npm scripts are listed in: package.json, package-lock.json. diff --git a/README.md b/README.md index 95726ce..83fc801 100644 --- a/README.md +++ b/README.md @@ -2,157 +2,35 @@ This is a RESTful FHIR API for the [Validated Relationship Service API](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service). -It includes: - -- `specification/` This [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers. -- `sandbox/` A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing. -- `scripts/` Utilities helpful to developers of this specification. -- `proxies/` Live (connecting to another service) and sandbox (using the sandbox container) Apigee API Proxy definitions. - Consumers of the API will find developer documentation on the [NHS Digital Developer Hub](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service). This repository does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Proxy Validated Relationship Service' repository which is not currently open source. +This repository includes: + +- [specification/validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml) - The [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers. +- `sandbox/` - A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing. +- `scripts/` - Utilities helpful to developers for the development and release of the specification. +- `proxies/` - Live and sandbox Apigee API Proxy definitions. + +## Table of Contents + - [validated-relationships-service-api](#validated-relationships-service-api) + - [Table of Contents](#table-of-contents) - [Contributing](#contributing) - - [Licensing](#licensing) - [Development \& Testing](#development--testing) - - [Caveats](#caveats) - - [Swagger UI](#swagger-ui) - - [Apigee Portal](#apigee-portal) - - [Platform setup](#platform-setup) - - [Detailed folder walk through](#detailed-folder-walk-through) - - [`/.github`:](#github) - - [`/azure`:](#azure) - - [`/proxies`:](#proxies) - - [`/sandbox`:](#sandbox) - - [Development](#development) - - [`/scripts`:](#scripts) - - [`/specification`:](#specification) - - [`/tests`:](#tests) - - [`Makefile`:](#makefile) - - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) - - [`manifest_template.yml`:](#manifest_templateyml) - - [Package management:](#package-management) - + - [Licensing](#licensing) ## Contributing Contributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](./CONTRIBUTING.md) and the [community code of conduct](./CODE_OF_CONDUCT.md). -### Licensing - -This code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses. - -The contents of this repository are protected by Crown Copyright (C). - ## Development & Testing -All development commands and documentation can be found in the [DEVELOPMENT_GUIDE.md](./CONTRIBUTING.md) file. - -### Caveats - -#### Swagger UI - -Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead. - -#### Apigee Portal - -The Apigee portal will not automatically pull examples from schemas, you must specify them manually. - -### Platform setup - -As currently defined in your `proxies` folder, your proxies do pretty much nothing. -Telling Apigee how to connect to your backend requires a _Target Server_, which you should call named `validated-relationships-service-api-target`. -Our _Target Servers_ defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure) repository. - -:bulb: For Sandbox-running environments (`test`) these need to be present for successful deployment but can be set to empty/dummy values. - -### Detailed folder walk through - -To get started developing your API use this template repo alongside guidance provided by the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Deliver+your+API) - -#### `/.github`: - -This folder contains templates that can be customised for items such as opening pull requests or issues within the repo - -`/.github/workflows`: This folder contains templates for GitHub action workflows such as: - -- `pr-lint.yaml`: This workflow template shows how to link Pull Request's to Jira tickets and runs when a pull request is opened. -- `continuous-integration.yml`: This workflow template shows how to publish a Github release when pushing to master. -- `sandbox-checks.yaml`: This workflow checks the sandbox meets the formatting and linting rules (Black + Flake8). Also it runs the sandbox unit tests (Pytest) -- `dependency-review.yml`: This workflow checks for any vulnerabilities in dependencies to be added to the project. -- `codeql-analysis.yml`: This workflow checks for any code vulnerabilities in the project. - -#### `/azure`: - -Contains templates defining Azure Devops pipelines. By default the following pipelines are available: - -- `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. By default this pipeline is enabled for all branches. -- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. You can run automated and manual tests against these while you develop. By default this pipeline will deploy to internal-dev, but the template can be amended to add other environments as required. -- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master. - -The `project.yml` file needs to be populated with your service names to make them available to the pipelines +All development commands and documentation can be found in [DEVELOPMENT_GUIDE.md](./DEVELOPMENT_GUIDE.md). -`/azure/templates`: Here you can define reusable actions, such as running tests, and call these actions during Azure Devops pipelines. - -#### `/proxies`: - -This folder contains files relating to your Apigee API proxy. - -There are 2 folders `/live` and `/sandbox` allowing you to define a different proxy for sandbox use. By default, this sandbox proxy is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo) - -Within the `live/apiproxy` and `sandbox/apiproxy` folders are: - -`/proxies/default.xml`: Defines the proxy's Flows. Flows define how the proxy should handle different requests. By default, \_ping and \_status endpoint flows are defined. -See the APM confluence for more information on how the [\_ping](https://nhsd-confluence.digital.nhs.uk/display/APM/_ping+endpoint) and [\_status](https://nhsd-confluence.digital.nhs.uk/display/APM/_status+endpoint) endpoints work. - -`/policies`: Populated with a set of standard XML Apigee policies that can be used in flows. - -`/resources/jsc`: Snippets of javascript code that are used in Apigee Javascript policies. For more info about Javascript policies see [here](https://docs.apigee.com/api-platform/reference/policies/javascript-policy) - -`/targets`: The XMLs within these folders set up target definitions which allow connections to external target servers. The sandbox target definition is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo). For more info on setting up a target server see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Setting+up+a+target+server) - -#### `/sandbox`: - -Sandbox provides a API for exploring the Proxy API. It uses pre-canned responses to most common scenarios. - -##### Development - -For information on how to develop the sandbox API see [README.md](sandbox/README.md) - -#### `/scripts`: - -Contains useful scripts that are used throughout the project, for example in Makefile and Github workflows - -#### `/specification`: - -Create an OpenAPI Specification to document your API. For more information about developing specifications see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Documenting+your+API). - -#### `/tests`: - -End to End tests. These tests are written in Python and use the PyTest test runner. Before running these tests you will need to set environment variables. The `test_endpoint.py` file provides a template of how to set up tests which test your api endpoints. For more information about testing your API see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Testing+your+API). - -#### `Makefile`: - -Useful make targets to get started including: installing dependencies and running smoke tests. - -#### `ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`: - -These files are required to deploy containers alongside your Apigee proxy during the Azure Devops `azure-build-pipeline`. In this template repo we are deploying our sandbox container which is used as the target server for the sandbox proxy. - -`ecs-proxies-containers.yml`: The path to a container's Dockerfile is defined here. This path needs to be defined to allow containers to be pushed to our repository during the `azure-build-pipeline`. - -`ecs-proxies-deploy.yml` : Here you can define config for your container deployment. - -For more information about deploying ECS containers see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Developing+ECS+proxies#DevelopingECSproxies-Buildingandpushingdockercontainers). - -#### `manifest_template.yml`: - -This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Manifest.yml+reference). - -#### Package management: +### Licensing -This template uses poetry for python dependency management, and uses these files: poetry.lock, poetry.toml, pyproject.toml. +This code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses. -Node dependencies of this template project and some npm scripts are listed in: package.json, package-lock.json. +The contents of this repository are protected by Crown Copyright (C). From b25351691fd909bff8c0905c944dd7763b2ed3ec Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Wed, 23 Oct 2024 11:34:42 +0100 Subject: [PATCH 5/9] NPA-3332 Add releasing a new schema version documentation --- CONTRIBUTING.md | 10 ---------- DEVELOPMENT_GUIDE.md | 18 ++++++++++++++++++ README.md | 18 +++++++++++------- 3 files changed, 29 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bbdb7fe..a41f180 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,16 +6,6 @@ - [Merge responsibility](#merge-responsibility) - [Branch naming](#branch-naming) - [Commit messages](#commit-messages) - - [Development](#development) - - [Requirements](#requirements) - - [Install](#install) - - [Updating hooks](#updating-hooks) - - [Environment Variables](#environment-variables) - - [Make commands](#make-commands) - - [Testing](#testing) - - [VS Code Plugins](#vs-code-plugins) - - [Emacs Plugins](#emacs-plugins) - - [Speccy](#speccy) ## Raising an Issue diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md index 045f3f4..781ed91 100644 --- a/DEVELOPMENT_GUIDE.md +++ b/DEVELOPMENT_GUIDE.md @@ -1,7 +1,11 @@ # Development Guide +This documentation is intended for developers to develop the schema, sandbox and proxies. It may be used by developers working within the NHS Digital organisation and outside contributors. + +## Table of Contents - [Development Guide](#development-guide) + - [Table of Contents](#table-of-contents) - [Development](#development) - [Requirements](#requirements) - [Install](#install) @@ -29,6 +33,7 @@ - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) - [`manifest_template.yml`:](#manifest_templateyml) - [Package management:](#package-management) + - [Releasing a new schema version](#releasing-a-new-schema-version) ## Development @@ -201,3 +206,16 @@ This file defines 2 dictionaries of fields that are required for the Apigee depl This template uses poetry for python dependency management, and uses these files: poetry.lock, poetry.toml, pyproject.toml. Node dependencies of this template project and some npm scripts are listed in: package.json, package-lock.json. + +## Releasing a new schema version + +To release a new version of the schema, follow the steps below: + +1. Update the version number in [specification/validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml). +2. Update the Postman collection - [postman/Validate Relationship Service Sandbox.postman_collection.json](./postman/Validate%20Relationship%20Service%20Sandbox.postman_collection.json). + 1. Documentation on how to update the Postman collection can be found [here](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=874694621). +3. Update the sandbox - [sandbox](./sandbox). +4. Create a pull request with the changes. +5. Once the pull request has been approved, merge it into the `master` branch. +6. Request a schema changes are published to the [Validated Relationship Service API](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service) page. + 1. Documentation on how to update the published specification page can be found [here](https://nhsd-confluence.digital.nhs.uk/display/NPA/Deploy+to+Public+Validated+Relationship+Service+API+Page) diff --git a/README.md b/README.md index 83fc801..df713f0 100644 --- a/README.md +++ b/README.md @@ -6,21 +6,25 @@ Consumers of the API will find developer documentation on the [NHS Digital Devel This repository does _not_ include the Validated Relationship Service FHIR API back-end. That is part of 'Proxy Validated Relationship Service' repository which is not currently open source. -This repository includes: - -- [specification/validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml) - The [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers. -- `sandbox/` - A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing. -- `scripts/` - Utilities helpful to developers for the development and release of the specification. -- `proxies/` - Live and sandbox Apigee API Proxy definitions. - ## Table of Contents - [validated-relationships-service-api](#validated-relationships-service-api) - [Table of Contents](#table-of-contents) + - [Repository Structure](#repository-structure) - [Contributing](#contributing) - [Development \& Testing](#development--testing) - [Licensing](#licensing) +## Repository Structure + +This repository includes: + +- [specification/validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml) - The [Open API Specification](https://swagger.io/docs/specification/about/) describes the endpoints, methods and messages exchanged by the API. Use it to generate interactive documentation; the contract between the API and its consumers. +- `sandbox/` - A flask (Python) API to provide mock implementation of the service. It's to be used as interactive documentation to illustrate interactions and concepts. It is not intended to provide an exhaustive/faithful environment suitable for full development and testing. +- `scripts/` - Utilities helpful to developers for the development and release of the specification. +- `proxies/` - Live and sandbox Apigee API Proxy definitions. + + ## Contributing Contributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](./CONTRIBUTING.md) and the [community code of conduct](./CODE_OF_CONDUCT.md). From e790e7225a5ecc3cafd5e92507f1c7e450a734d1 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:42:49 +0100 Subject: [PATCH 6/9] NPA-3332 Begin Reworking Development Guide --- .vscode/extensions.json | 6 ++++ DEVELOPMENT_GUIDE.md | 74 ++++++++--------------------------------- 2 files changed, 20 insertions(+), 60 deletions(-) create mode 100644 .vscode/extensions.json diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..b28b8a1 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,6 @@ +{ + "recommendations": [ + "mermade.openapi-lint", + "42Crunch.vscode-openapi" + ] +} diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md index 781ed91..baaab64 100644 --- a/DEVELOPMENT_GUIDE.md +++ b/DEVELOPMENT_GUIDE.md @@ -8,14 +8,8 @@ This documentation is intended for developers to develop the schema, sandbox and - [Table of Contents](#table-of-contents) - [Development](#development) - [Requirements](#requirements) - - [Install](#install) - - [Updating hooks](#updating-hooks) - - [Environment Variables](#environment-variables) - [Make commands](#make-commands) - [Testing](#testing) - - [VS Code Plugins](#vs-code-plugins) - - [Emacs Plugins](#emacs-plugins) - - [Speccy](#speccy) - [Caveats](#caveats) - [Swagger UI](#swagger-ui) - [Apigee Portal](#apigee-portal) @@ -32,42 +26,27 @@ This documentation is intended for developers to develop the schema, sandbox and - [`Makefile`:](#makefile) - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) - [`manifest_template.yml`:](#manifest_templateyml) - - [Package management:](#package-management) - [Releasing a new schema version](#releasing-a-new-schema-version) ## Development +> [!NOTE] +> Sandbox development is not documented here. Please see the [Sandbox README](./sandbox/README.md) for more information. + ### Requirements - GNU make -- nodejs + npm/yarn -- Python 3.8 + [poetry](https://github.com/python-poetry/poetry) +- nodejs 22+ + - npm 10.8+ +- Python 3.8 + + - [poetry](https://github.com/python-poetry/poetry) 1.8+ - Java 8+ -### Install - -``` -$ make install -``` - -#### Updating hooks - -You can install some pre-commit hooks to ensure you can't commit invalid spec changes by accident. These are also run -in CI, but it's useful to run them locally too. - -``` -$ make install -``` - -### Environment Variables - -Various scripts and commands rely on environment variables being set. These are documented with the commands. - -:bulb: Consider using [direnv](https://direnv.net/) to manage your environment variables during development and maintaining your own `.envrc` file - the values of these variables will be specific to you and/or sensitive. - ### Make commands -There are `make` commands that alias some of this functionality: +To run the below make targets you will first need to run `make install-node` + +There are `make` commands that alias scripts in the `package.json` - `lint` -- Lints the spec and code - `publish` -- Outputs the specification as a **single file** into the `build/` directory @@ -75,36 +54,17 @@ There are `make` commands that alias some of this functionality: ### Testing -Each API and team is unique. We encourage you to use a `test/` folder in the root of the project, and use whatever testing frameworks or apps your team feels comfortable with. It is important that the URL your test points to be configurable. We have included some stubs in the Makefile for running tests. - -### VS Code Plugins - -- [openapi-lint](https://marketplace.visualstudio.com/items?itemName=mermade.openapi-lint) resolves links and validates entire spec with the 'OpenAPI Resolve and Validate' command -- [OpenAPI (Swagger) Editor](https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi) provides sidebar navigation +A minimal Pytest test suite is available under the [tests](./tests) folder. These test the Apigee Proxy is set up. These tests are written in Python and use the PyTest test runner. -### Emacs Plugins +A majority of the testing is co-located with the application in the `Proxy Validated Relationship Service` repository that is not currently open source. -- [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help - -### Speccy - -> [Speccy](http://speccy.io/) _A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution._ - -Speccy does the lifting for the following npm scripts: - -- `test` -- Lints the definition -- `publish` -- Outputs the specification as a **single file** into the `build/` directory -- `serve` -- Serves a preview of the specification in human-readable format - -(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the _developerjack_ blog.) - -:bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file. +The test dependencies can be installed by running `make install` from the root directory of this project. ### Caveats #### Swagger UI -Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead. +Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so when publishing the schema to the API catalogue it uses `make publish` which under the hood uses `speccy serve` instead. #### Apigee Portal @@ -201,12 +161,6 @@ For more information about deploying ECS containers see the [API Producer Zone c This file defines 2 dictionaries of fields that are required for the Apigee deployment. For more info see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Manifest.yml+reference). -#### Package management: - -This template uses poetry for python dependency management, and uses these files: poetry.lock, poetry.toml, pyproject.toml. - -Node dependencies of this template project and some npm scripts are listed in: package.json, package-lock.json. - ## Releasing a new schema version To release a new version of the schema, follow the steps below: From 92d928dc96f5d96454178e15d5f8384dc6b6e81d Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:55:43 +0100 Subject: [PATCH 7/9] NPA-3332 Prettify MD files --- CODE_OF_CONDUCT.md | 26 +++++++++++------------ CONTRIBUTING.md | 12 +++++------ DEVELOPMENT_GUIDE.md | 50 ++++++++++++++++++++++---------------------- README.md | 13 ++++++------ SECURITY.md | 11 ++++++++-- 5 files changed, 59 insertions(+), 53 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 65cf5ff..b5d8a9a 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -14,22 +14,22 @@ appearance, race, religion, or sexual identity and orientation. Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting +- The use of sexualized language or imagery and unwelcome sexual attention or + advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic + address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting ## Our Responsibilities diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a41f180..6cd8b68 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,11 @@ # Contribution Guidelines -- [Contribution Guidelines](#contribution-guidelines) - - [Raising an Issue](#raising-an-issue) - - [Contributing code](#contributing-code) - - [Merge responsibility](#merge-responsibility) - - [Branch naming](#branch-naming) - - [Commit messages](#commit-messages) +- [Contribution Guidelines](#contribution-guidelines) + - [Raising an Issue](#raising-an-issue) + - [Contributing code](#contributing-code) + - [Merge responsibility](#merge-responsibility) + - [Branch naming](#branch-naming) + - [Commit messages](#commit-messages) ## Raising an Issue diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md index baaab64..ff61c7c 100644 --- a/DEVELOPMENT_GUIDE.md +++ b/DEVELOPMENT_GUIDE.md @@ -4,29 +4,29 @@ This documentation is intended for developers to develop the schema, sandbox and ## Table of Contents -- [Development Guide](#development-guide) - - [Table of Contents](#table-of-contents) - - [Development](#development) - - [Requirements](#requirements) - - [Make commands](#make-commands) - - [Testing](#testing) - - [Caveats](#caveats) - - [Swagger UI](#swagger-ui) - - [Apigee Portal](#apigee-portal) - - [Platform setup](#platform-setup) - - [Detailed folder walk through](#detailed-folder-walk-through) - - [`/.github`:](#github) - - [`/azure`:](#azure) - - [`/proxies`:](#proxies) - - [`/sandbox`:](#sandbox) - - [Development](#development-1) - - [`/scripts`:](#scripts) - - [`/specification`:](#specification) - - [`/tests`:](#tests) - - [`Makefile`:](#makefile) - - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) - - [`manifest_template.yml`:](#manifest_templateyml) - - [Releasing a new schema version](#releasing-a-new-schema-version) +- [Development Guide](#development-guide) + - [Table of Contents](#table-of-contents) + - [Development](#development) + - [Requirements](#requirements) + - [Make commands](#make-commands) + - [Testing](#testing) + - [Caveats](#caveats) + - [Swagger UI](#swagger-ui) + - [Apigee Portal](#apigee-portal) + - [Platform setup](#platform-setup) + - [Detailed folder walk through](#detailed-folder-walk-through) + - [`/.github`:](#github) + - [`/azure`:](#azure) + - [`/proxies`:](#proxies) + - [`/sandbox`:](#sandbox) + - [Development](#development-1) + - [`/scripts`:](#scripts) + - [`/specification`:](#specification) + - [`/tests`:](#tests) + - [`Makefile`:](#makefile) + - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) + - [`manifest_template.yml`:](#manifest_templateyml) + - [Releasing a new schema version](#releasing-a-new-schema-version) ## Development @@ -37,9 +37,9 @@ This documentation is intended for developers to develop the schema, sandbox and - GNU make - nodejs 22+ - - npm 10.8+ + - npm 10.8+ - Python 3.8 + - - [poetry](https://github.com/python-poetry/poetry) 1.8+ + - [poetry](https://github.com/python-poetry/poetry) 1.8+ - Java 8+ ### Make commands diff --git a/README.md b/README.md index df713f0..0700ea6 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,12 @@ This repository does _not_ include the Validated Relationship Service FHIR API b ## Table of Contents -- [validated-relationships-service-api](#validated-relationships-service-api) - - [Table of Contents](#table-of-contents) - - [Repository Structure](#repository-structure) - - [Contributing](#contributing) - - [Development \& Testing](#development--testing) - - [Licensing](#licensing) +- [validated-relationships-service-api](#validated-relationships-service-api) + - [Table of Contents](#table-of-contents) + - [Repository Structure](#repository-structure) + - [Contributing](#contributing) + - [Development \& Testing](#development--testing) + - [Licensing](#licensing) ## Repository Structure @@ -24,7 +24,6 @@ This repository includes: - `scripts/` - Utilities helpful to developers for the development and release of the specification. - `proxies/` - Live and sandbox Apigee API Proxy definitions. - ## Contributing Contributions to this project are welcome from anyone, providing that they conform to the [guidelines for contribution](./CONTRIBUTING.md) and the [community code of conduct](./CODE_OF_CONDUCT.md). diff --git a/SECURITY.md b/SECURITY.md index fb74718..2d5561a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,23 +7,28 @@ private data managed by our systems, please do not hesitate to contact us using the methods outlined below. ## Reporting a vulnerability + **PLEASE NOTE: Email and HackerOne are our preferred methods of receiving reports.** ### Email + If you wish to notify us of a vulnerability via email, please include detailed information on the nature of the vulnerability and any steps required to reproduce it. You can reach us at: -* cybersecurity@nhs.net -* api.management@nhs.net + +- cybersecurity@nhs.net +- api.management@nhs.net ### HackerOne + If you are registered with HackerOne and have been admitted to the NHS Programme, you can report directly to us at: https://hackerone.com/nhs ### NCSC + You can send your report to the National Cyber Security Centre, who will assess your report and pass it on to NHS Digital if necessary. @@ -31,8 +36,10 @@ You can report vulnerabilities here: https://www.ncsc.gov.uk/information/vulnerability-reporting ### OpenBugBounty + We also accept bug reports via OpenBugBounty: https://www.openbugbounty.org/ ## General Security Enquiries + If you have general enquiries regarding our cyber security, please reach out to us at cybersecurity@nhs.net From 2e55c3513272cd2ab22cc9158c6eb7fb05ef9f35 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:23:43 +0100 Subject: [PATCH 8/9] NPA-3332 Update Development Guide based on feedback --- DEVELOPMENT_GUIDE.md | 79 +++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 45 deletions(-) diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md index ff61c7c..ce5fdc4 100644 --- a/DEVELOPMENT_GUIDE.md +++ b/DEVELOPMENT_GUIDE.md @@ -2,6 +2,9 @@ This documentation is intended for developers to develop the schema, sandbox and proxies. It may be used by developers working within the NHS Digital organisation and outside contributors. +> [!WARNING] +> Some of this documentation is specific to the maintainers of this repository and is only available to NHS England staff. + ## Table of Contents - [Development Guide](#development-guide) @@ -10,16 +13,11 @@ This documentation is intended for developers to develop the schema, sandbox and - [Requirements](#requirements) - [Make commands](#make-commands) - [Testing](#testing) - - [Caveats](#caveats) - - [Swagger UI](#swagger-ui) - - [Apigee Portal](#apigee-portal) - [Platform setup](#platform-setup) - [Detailed folder walk through](#detailed-folder-walk-through) - [`/.github`:](#github) - [`/azure`:](#azure) - [`/proxies`:](#proxies) - - [`/sandbox`:](#sandbox) - - [Development](#development-1) - [`/scripts`:](#scripts) - [`/specification`:](#specification) - [`/tests`:](#tests) @@ -27,6 +25,9 @@ This documentation is intended for developers to develop the schema, sandbox and - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) - [`manifest_template.yml`:](#manifest_templateyml) - [Releasing a new schema version](#releasing-a-new-schema-version) + - [Caveats](#caveats) + - [Swagger UI](#swagger-ui) + - [Apigee Portal](#apigee-portal) ## Development @@ -59,56 +60,42 @@ A minimal Pytest test suite is available under the [tests](./tests) folder. Thes A majority of the testing is co-located with the application in the `Proxy Validated Relationship Service` repository that is not currently open source. The test dependencies can be installed by running `make install` from the root directory of this project. - -### Caveats - -#### Swagger UI - -Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so when publishing the schema to the API catalogue it uses `make publish` which under the hood uses `speccy serve` instead. - -#### Apigee Portal - -The Apigee portal will not automatically pull examples from schemas, you must specify them manually. +To run tests run `make test` from the project root. Or for Smoke tests run `make smoketest` ### Platform setup -As currently defined in your `proxies` folder, your proxies do pretty much nothing. -Telling Apigee how to connect to your backend requires a _Target Server_, which you should call named `validated-relationships-service-api-target`. -Our _Target Servers_ defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure) repository. +Apigee is setup for all live environments (dev, qa, int, prod) proxy the request to a target server. The target server on Apigee should be named `validated-relationships-service-api-target`. +Target Servers defined in the [api-management-infrastructure](https://github.com/NHSDigital/api-management-infrastructure/blob/master/ansible/roles/apigee-keystores-refs-targetservers/vars/main/target-servers.yml) repository. -:bulb: For Sandbox-running environments (`test`) these need to be present for successful deployment but can be set to empty/dummy values. +Sandbox environments use Apigee to proxy the request to an AWS ECS container. ### Detailed folder walk through -To get started developing your API use this template repo alongside guidance provided by the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Deliver+your+API) +For further information about Apigee and APIM see [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Deliver+your+API) #### `/.github`: -This folder contains templates that can be customised for items such as opening pull requests or issues within the repo +`/.github/workflows`: This folder contains GitHub workflows, these workflow are mainly used to check pull requests and publish releases. -`/.github/workflows`: This folder contains templates for GitHub action workflows such as: - -- `pr-lint.yaml`: This workflow template shows how to link Pull Request's to Jira tickets and runs when a pull request is opened. -- `continuous-integration.yml`: This workflow template shows how to publish a Github release when pushing to master. +- `pr-lint.yaml`: This workflow links Pull Request's to Jira tickets and runs when a pull request is opened/updated. +- `continuous-integration.yml`: This workflow publishes a Github release when pushing to master. - `sandbox-checks.yaml`: This workflow checks the sandbox meets the formatting and linting rules (Black + Flake8). Also it runs the sandbox unit tests (Pytest) - `dependency-review.yml`: This workflow checks for any vulnerabilities in dependencies to be added to the project. - `codeql-analysis.yml`: This workflow checks for any code vulnerabilities in the project. #### `/azure`: -Contains templates defining Azure Devops pipelines. By default the following pipelines are available: - -- `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. By default this pipeline is enabled for all branches. -- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. You can run automated and manual tests against these while you develop. By default this pipeline will deploy to internal-dev, but the template can be amended to add other environments as required. -- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, typically when you merge to master. +Contains Azure Devops pipelines for building and deploying to Apigee: -The `project.yml` file needs to be populated with your service names to make them available to the pipelines +- `azure-build-pipeline.yml`: Assembles the contents of your repository into a single file ("artifact") on Azure Devops and pushes any containers to our Docker registry. This pipeline is enabled for all branches. +- `azure-pr-pipeline.yml`: Deploys ephemeral versions of your proxy/spec to Apigee (and docker containers on AWS) to internal environments. This will deploy a internal-dev environment and internal-dev-sandbox for each pull request. +- `azure-release-pipeline.yml`: Deploys the long-lived version of your pipeline to internal and external environments, when you merge to master. `/azure/templates`: Here you can define reusable actions, such as running tests, and call these actions during Azure Devops pipelines. #### `/proxies`: -This folder contains files relating to your Apigee API proxy. +This folder contains files relating to the Apigee API proxy. There are 2 folders `/live` and `/sandbox` allowing you to define a different proxy for sandbox use. By default, this sandbox proxy is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo) @@ -123,21 +110,13 @@ See the APM confluence for more information on how the [\_ping](https://nhsd-con `/targets`: The XMLs within these folders set up target definitions which allow connections to external target servers. The sandbox target definition is implemented to route to the sandbox target server (code for this sandbox is found under /sandbox of this template repo). For more info on setting up a target server see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Setting+up+a+target+server) -#### `/sandbox`: - -Sandbox provides a API for exploring the Proxy API. It uses pre-canned responses to most common scenarios. - -##### Development - -For information on how to develop the sandbox API see [README.md](sandbox/README.md) - #### `/scripts`: -Contains useful scripts that are used throughout the project, for example in Makefile and Github workflows +Contains useful scripts that are used throughout the project. Mainly Python scripts used in the release process. #### `/specification`: -Create an OpenAPI Specification to document your API. For more information about developing specifications see the [API Producer Zone confluence](https://nhsd-confluence.digital.nhs.uk/display/APM/Documenting+your+API). +Contains the OpenAPI specification - [validated-relationships-service-api.yaml](./specification/validated-relationships-service-api.yaml) #### `/tests`: @@ -145,13 +124,13 @@ End to End tests. These tests are written in Python and use the PyTest test runn #### `Makefile`: -Useful make targets to get started including: installing dependencies and running smoke tests. +Contains make targets to run parts of the project such as installing dependencies and running smoke tests. #### `ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`: -These files are required to deploy containers alongside your Apigee proxy during the Azure Devops `azure-build-pipeline`. In this template repo we are deploying our sandbox container which is used as the target server for the sandbox proxy. +These files are required to deploy containers alongside your Apigee proxy during the Azure Devops `azure-build-pipeline`. -`ecs-proxies-containers.yml`: The path to a container's Dockerfile is defined here. This path needs to be defined to allow containers to be pushed to our repository during the `azure-build-pipeline`. +`ecs-proxies-containers.yml`: The path to a container's Dockerfile is defined here. This path needs to be defined to allow containers to be pushed to our repository during the `azure-build-pipeline`. This is used for the sandbox proxy docker container. `ecs-proxies-deploy.yml` : Here you can define config for your container deployment. @@ -173,3 +152,13 @@ To release a new version of the schema, follow the steps below: 5. Once the pull request has been approved, merge it into the `master` branch. 6. Request a schema changes are published to the [Validated Relationship Service API](https://digital.nhs.uk/developer/api-catalogue/validated-relationship-service) page. 1. Documentation on how to update the published specification page can be found [here](https://nhsd-confluence.digital.nhs.uk/display/NPA/Deploy+to+Public+Validated+Relationship+Service+API+Page) + +### Caveats + +#### Swagger UI + +Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so when publishing the schema to the API catalogue it uses `make publish` which under the hood uses `speccy serve` instead. + +#### Apigee Portal + +The Apigee portal will not automatically pull examples from schemas, you must specify them manually. From f82971588ba86706c228b580196c712d3c1ac556 Mon Sep 17 00:00:00 2001 From: Jack Plowman <62281988+JackPlowman@users.noreply.github.com> Date: Thu, 24 Oct 2024 13:25:03 +0100 Subject: [PATCH 9/9] NPA-3332 Reword warning --- DEVELOPMENT_GUIDE.md | 44 ++++++++++++++++++++++---------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/DEVELOPMENT_GUIDE.md b/DEVELOPMENT_GUIDE.md index ce5fdc4..fa4ba4b 100644 --- a/DEVELOPMENT_GUIDE.md +++ b/DEVELOPMENT_GUIDE.md @@ -3,31 +3,31 @@ This documentation is intended for developers to develop the schema, sandbox and proxies. It may be used by developers working within the NHS Digital organisation and outside contributors. > [!WARNING] -> Some of this documentation is specific to the maintainers of this repository and is only available to NHS England staff. +> Some of the documentation and links are specific to the maintainers of this repository and are only available to NHS England staff. ## Table of Contents -- [Development Guide](#development-guide) - - [Table of Contents](#table-of-contents) - - [Development](#development) - - [Requirements](#requirements) - - [Make commands](#make-commands) - - [Testing](#testing) - - [Platform setup](#platform-setup) - - [Detailed folder walk through](#detailed-folder-walk-through) - - [`/.github`:](#github) - - [`/azure`:](#azure) - - [`/proxies`:](#proxies) - - [`/scripts`:](#scripts) - - [`/specification`:](#specification) - - [`/tests`:](#tests) - - [`Makefile`:](#makefile) - - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) - - [`manifest_template.yml`:](#manifest_templateyml) - - [Releasing a new schema version](#releasing-a-new-schema-version) - - [Caveats](#caveats) - - [Swagger UI](#swagger-ui) - - [Apigee Portal](#apigee-portal) +- [Development Guide](#development-guide) + - [Table of Contents](#table-of-contents) + - [Development](#development) + - [Requirements](#requirements) + - [Make commands](#make-commands) + - [Testing](#testing) + - [Platform setup](#platform-setup) + - [Detailed folder walk through](#detailed-folder-walk-through) + - [`/.github`:](#github) + - [`/azure`:](#azure) + - [`/proxies`:](#proxies) + - [`/scripts`:](#scripts) + - [`/specification`:](#specification) + - [`/tests`:](#tests) + - [`Makefile`:](#makefile) + - [`ecs-proxies-containers.yml ` and `ecs-proxies-deploy.yml`:](#ecs-proxies-containersyml--and-ecs-proxies-deployyml) + - [`manifest_template.yml`:](#manifest_templateyml) + - [Releasing a new schema version](#releasing-a-new-schema-version) + - [Caveats](#caveats) + - [Swagger UI](#swagger-ui) + - [Apigee Portal](#apigee-portal) ## Development