NPA-3332 Begin Reworking Development Guide

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "mermade.openapi-lint",
+    "42Crunch.vscode-openapi"
+  ]
+}

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,79 +26,45 @@ 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
 -   `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
+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: