README

Author: JamesW1-NHS

README.specification.md

@@ -54,41 +54,40 @@ 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
 
-### Testing
+Note: the npm scripts are no longer based on Speccy.
 
-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.
+### Modifying the OAS file
 
-### VS Code Plugins
+Note that the master OAS file is now the **YAML** version, as it is far easier to maintain than the JSON.
 
-- [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
+To review your modifications, use Swagger Editor (https://editor.swagger.io).
 
-### Emacs Plugins
+### Update the OAS file to the public website
 
-- [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help
+Note that this is currently a **manual** process.
 
-### Speccy
+After modifying the OAS YAML file, run `make oas` on your local machine. This will output the specification into `specification/immunisation-fhir-api.oas.json`. This is a **minified, versioned** JSON file suitable for sending to APIM
+for uploading to the pubic website.
 
-> [Speccy](http://speccy.io/) _A handy toolkit for OpenAPI, with a linter to enforce quality rules, documentation rendering, and resolution._
+Please push the minified JSON file to GitHub to along with the YAML file to keep the two in sync, and so that the JSON file can be
+re-submitted to APIM without re-processing if need be.
 
-Speccy does the lifting for the following npm scripts:
+### Testing
 
-- `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
+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.
 
-(Workflow detailed in a [post](https://developerjack.com/blog/2018/maintaining-large-design-first-api-specs/) on the _developerjack_ blog.)
+### VS Code Plugins
 
-:bulb: The `publish` command is useful when uploading to Apigee which requires the spec as a single file.
+- [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
 
-### Caveats
+### Emacs Plugins
 
-#### Swagger UI
+- [**openapi-yaml-mode**](https://github.com/esc-emacs/openapi-yaml-mode) provides syntax highlighting, completion, and path help
 
-Swagger UI unfortunately doesn't correctly render `$ref`s in examples, so use `speccy serve` instead.
+### Caveats
 
 #### Apigee Portal