VED-494: OAS (#1056)

* init: YAML as master

* prettier

* deleted JSON

* temp: --skip-rule=no-invalid-media-type-examples

* make oas

* make oas II

* add generated immunisation-fhir-api.oas.json

* read-only

* read-only II

* prettier

* README re. hooks

* README

* review

Author: JamesW1-NHS

.prettierignore

@@ -5,3 +5,6 @@
 # TODO - investigate
 /infrastructure/proxies/live/apiproxy/resources/jsc/
 /infrastructure/proxies/sandbox/apiproxy/resources/jsc/
+
+# The oas.json file is deliberately minified
+immunisation-fhir-api.oas.json

Makefile

@@ -3,7 +3,7 @@ SHELL=/usr/bin/env bash -euo pipefail
 PYTHON_PROJECT_DIRS_WITH_UNIT_TESTS = lambdas/backend lambdas/ack_backend lambdas/batch_processor_filter lambdas/delta_backend lambdas/filenameprocessor lambdas/id_sync lambdas/mesh_processor lambdas/mns_subscription lambdas/recordforwarder lambdas/recordprocessor lambdas/redis_sync lambdas/shared
 PYTHON_PROJECT_DIRS = tests/e2e tests/e2e_batch quality_checks $(PYTHON_PROJECT_DIRS_WITH_UNIT_TESTS)
 
-.PHONY: install lint format format-check clean publish build-proxy release initialise-all-python-venvs update-all-python-dependencies run-all-python-unit-tests build-all-docker-images
+.PHONY: install lint format format-check clean publish oas build-proxy release initialise-all-python-venvs update-all-python-dependencies run-all-python-unit-tests build-all-docker-images
 
 #Installs dependencies using npm.
 install:
@@ -19,18 +19,26 @@ format:
 format-check:
 	npm run format-check
 
-#Removes build/ + dist/ directories
+#Removes build/, dist/ and sandbox/specification/ directories
 clean:
 	rm -rf build
 	rm -rf dist
+	rm -rf sandbox/specification
 
-#Creates the fully expanded OAS spec in json
+#Creates the OAS spec in JSON for sandbox
 publish: clean
 	mkdir -p build
 	npm run publish 2> /dev/null
 	cp build/immunisation-fhir-api.json sandbox/
 	cp -r specification sandbox/specification
 
+#Creates a minified OAS spec in JSON for sending to APIM
+oas: publish
+	mkdir -p oas
+	rm -f specification/immunisation-fhir-api.json
+	jq -c . build/immunisation-fhir-api.json > oas/immunisation-fhir-api.json
+	chmod -w oas/immunisation-fhir-api.json
+
 #Runs build proxy script
 build-proxy:
 	utilities/scripts/build_proxy.sh

README.specification.md

@@ -41,9 +41,7 @@ $ make install
 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-hooks
-```
+Note that this step is now done automatically in `make install` above. `make install-hooks` is no longer run.
 
 ### Environment Variables
 
@@ -56,8 +54,20 @@ Various scripts and commands rely on environment variables being set. These are
 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
+- `publish` -- Outputs the specification as a **single** JSON file into the `build/` directory
+
+### Modifying the OAS file
+
+Note that the master OAS file is now the **YAML** version, as it is far easier to maintain than the JSON.
+
+To review your modifications, use Swagger Editor (https://editor.swagger.io).
+
+### Update the OAS file to the public website
+
+Note that this is currently a **manual** process.
+
+After modifying the OAS YAML file, run `make oas` on your local machine. This will output the specification into `oas/immunisation-fhir-api.json`. This is a **minified** JSON file suitable for sending to APIM
+for uploading to the pubic website.
 
 ### Testing
 
@@ -72,26 +82,8 @@ Each API and team is unique. We encourage you to use a `test/` folder in the roo
 
 - [**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.
-
 ### 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.

package.json

@@ -3,7 +3,7 @@
   "version": "0.0.1",
   "description": "OAS (Swagger v3) API Definition for Template API",
   "scripts": {
-    "lint": "redocly lint --skip-rule=security-defined specification/immunisation-fhir-api.yaml",
+    "lint": "redocly lint --skip-rule=security-defined --skip-rule=no-invalid-media-type-examples specification/immunisation-fhir-api.yaml",
     "format": "prettier --write .",
     "format-check": "prettier --check .",
     "publish": "redocly bundle specification/immunisation-fhir-api.yaml --remove-unused-components --ext json -o build/immunisation-fhir-api.json",
@@ -26,6 +26,6 @@
       "poetry -P quality_checks run ruff format"
     ],
     "*.tf": "terraform fmt",
-    "immunisation-fhir-api.{yaml,json}": "redocly lint --skip-rule=security-defined"
+    "immunisation-fhir-api.{yaml,json}": "redocly lint --skip-rule=security-defined --skip-rule=no-invalid-media-type-examples"
   }
 }