(automated) quality checks

[alamers]

As the pull request from @Jongmassey has shown, it is easy for errors to slip in. Right now, we more or less have a set of static files and rely on manual checking.

We should have an environment where we can build the documentation and also perform automated quality checks. For example, running
docker run wework/speccy lint https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml
(on a workstation with Docker installed), will give detailed feedback on things that need improving.

[alamers]

just a hint for working locally: you can mount your local checkout and run speccy against that:

docker run -v /Users/arjanl/ICAR/Release\ Candidate\ Messages/:/project wework/speccy lint exampleUrlScheme.yaml

[Jongmassey]

https://engineering.wework.com/our-api-specification-workflow-9337448d6ee6 This in an interesting medium post about wework's API development/CI workflow - might be useful

[cookeac]

Note that natively speccy complains about some JSON-Schema constructs, such as "$schema". That is supposed to be fixed in a later version of OpenAPI, but in the meantime you'll probably have seen you can use the -j switch with speccy to address this (apparently - I haven't tested it myself).

[ahokkonen]

just a hint for working locally: you can mount your local checkout and run speccy against that:

docker run -v /Users/arjanl/ICAR/Release\ Candidate\ Messages/:/project wework/speccy lint exampleUrlScheme.yaml

You can also do that directly in GitHub by creating "Action" for ICAR repo. Simpest one would be create action with such workflow:

name: JSON validation CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v1
    - name: JSON validation by wework/speccy container
      run: |
        docker run wework/speccy lint \
        https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.json

This will trigger automatic validation on each push commit

[cookeac]

I have added this validation to /.github/workflows in Master. At the moment it is failing until an error is corrected in icarConsignmentType.json. I have submitted a patch pull request to fix this.

[cookeac]

Error has been corrected, and the Speccy validation now works. Noted that we may wish to consider a change to Stoplight.io in future as Speccy is not being maintained and future changes to the JSON Schema specification might break the validation.