Merge ~lloydwaltersj/maas:oapi-linter into maas:master

[Jack Lloyd-Walters]

Add a linter for the OpenAPI spec

add the ability to lint the MAAS Http api against OAS3

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/355/consoleText
COMMIT: 94339310e45dd8f4e22296b5c0e2436ab1c66120

review: Needs Fixing

[Alexsander de Souza (alexsander-souza)]

use tox to handle the test environment

review: Needs Fixing

[Adam Collard (adam-collard)]

Don't think we should consider this a linter in the same way that we do the other linters.

It should be implemented as a test in the api package, alongside the API definition, documentation etc.

If this fails, it's not because we've used a deprecated way of writing Python, or sorted imports differently, it's a failure close to the OpenAPI feature.

review: Needs Fixing

[Alexsander de Souza (alexsander-souza)]

> If this fails, it's not because we've used a deprecated way of writing Python,
> or sorted imports differently, it's a failure close to the OpenAPI feature.

I think this is real linter, because if this fails it means that we failed to write valid documentation for whatever we are doing, not that the OpenAPI feature has a bug.

cd623b8... by Jack Lloyd-Walters on 2022-08-22

transition to tox

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/362/consoleText
COMMIT: cd623b889ddf406d2aef707052f647e22488f931

review: Needs Fixing

a90fe6e... by Jack Lloyd-Walters on 2022-08-22

change how oapi doccs are generated for linting

[Jack Lloyd-Walters (lloydwaltersj)]

> STATUS: FAILED
> LOG: http://maas-ci.internal:8080/job/maas-tester/362/consoleText
> COMMIT: cd623b889ddf406d2aef707052f647e22488f931

This is working exactly as expected, a successfull failure if you will!

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/363/consoleText
COMMIT: a90fe6e49bee699aa470cd374526654e94bcab95

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/392/consoleText
COMMIT: a90fe6e49bee699aa470cd374526654e94bcab95

review: Needs Fixing

39c02c3... by Jack Lloyd-Walters on 2022-08-26

bring branch up to parity

c0695f9... by Jack Lloyd-Walters on 2022-08-26

revert yaml.dump change

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/405/consoleText
COMMIT: c0695f98b1e9ced2ccb37447682b5c59fd50bb1d

review: Needs Fixing

4eaea74... by Jack Lloyd-Walters on 2022-08-26

remove make docs from lint

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/407/consoleText
COMMIT: 4eaea745bfebe77675dc6e03ae1047f4b182122e

review: Needs Fixing

2c01771... by Jack Lloyd-Walters on 2022-08-30

remove hardcoded openapi file location

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/438/consoleText
COMMIT: 2c01771792cbdf7cb63bed44851791f6f354df7b

review: Needs Fixing

6247138... by Jack Lloyd-Walters on 2022-08-31

bring branch up to parity

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/455/consoleText
COMMIT: 6247138baf4652bcd8ae945d9e173e0da87ccc99

review: Needs Fixing

b55d865... by Jack Lloyd-Walters on 2022-09-01

bring branch up to parity

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/487/consoleText
COMMIT: b55d865e978a03383164554460790a26ffe24b55

review: Needs Fixing

8421bf8... by Jack Lloyd-Walters on 2022-09-02

generate spec if missing

bb8d96d... by Jack Lloyd-Walters on 2022-09-02

make linter depend on spec

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 8421bf8f4b32f39fa8592cf821d836f6ba501b29

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: bb8d96d2bf145e94f54b57cb39b01216d3871108

review: Approve

[Adam Collard (adam-collard)]

review: Approve

[Adam Collard (adam-collard)]

review: Abstain

921393f... by Jack Lloyd-Walters on 2022-09-02

remove help supression

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/506/consoleText
COMMIT: 921393ffd0cc2f1eabb8a6444afc8b3a49869182

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 921393ffd0cc2f1eabb8a6444afc8b3a49869182

review: Approve

[Alexsander de Souza (alexsander-souza)]

+1

review: Approve

46f3269... by Jack Lloyd-Walters on 2022-09-02

remove lint-oapi from lint target

1cbbc49... by Jack Lloyd-Walters on 2022-09-02

move oapi linter to test phase

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-linter lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 1cbbc4976c25603e92dad0e557d623ebe889a17f

review: Approve

diff --git a/Makefile b/Makefile
index 5a5c2af..903c5af 100644
--- a/Makefile
+++ b/Makefile
@@ -121,7 +121,7 @@ go-bins:
 	$(MAKE) -j -C src/host-info build
 .PHONY: go-bins
 
-test: test-missing-migrations test-py
+test: test-missing-migrations test-py lint-oapi
 .PHONY: test
 
 test-missing-migrations: bin/database bin/maas-region
@@ -166,6 +166,11 @@ lint-py-linefeeds:
 		(echo "Lint check failed; run make format to fix DOS linefeeds."; false)
 .PHONY: lint-py-linefeeds
 
+# Open API Spec
+lint-oapi: openapi.yaml
+	@tox -e oapi
+.PHONY: lint-oapi
+
 # Go fmt
 lint-go:
 	@find src/ \( -name pkg -o -name vendor \) -prune -o -name '*.go' -exec gofmt -l {} + | \
diff --git a/setup.cfg b/setup.cfg
index 5d02873..c4c7faa 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -94,6 +94,7 @@ lint_files =
   src/provisioningserver/refresh/50-maas-01-commissioning
   utilities/bin2python.py
   utilities/check-imports
+  utilities/check-oapi
   utilities/import-db-dump
   utilities/python_standard_libs.py
   utilities/snap-bind-mounts
@@ -109,6 +110,9 @@ deps_lint =
   cogapp == 3.3.0
   click == 8.1.3
 
+deps_oapi =
+  openapi-spec-validator == 0.4.0
+
 [flake8]
 ignore = E203, E266, E501, W503, W504
 exclude =
@@ -116,7 +120,7 @@ exclude =
 
 [tox:tox]
 skipsdist = True
-envlist = format,lint
+envlist = format,lint,oapi
 
 [testenv:format]
 deps = {[globals]deps_lint}
@@ -132,3 +136,8 @@ commands =
   black --check {[globals]lint_files}
   flake8 {[globals]lint_files}
   cog --check --verbosity=1 {[globals]cog_files}
+
+[testenv:oapi]
+deps = {[globals]deps_oapi}
+commands =
+  python3 utilities/check-oapi openapi.yaml
\ No newline at end of file
diff --git a/utilities/check-oapi b/utilities/check-oapi
new file mode 100755
index 0000000..d77ae23
--- /dev/null
+++ b/utilities/check-oapi
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+
+"""Script to ensure that an OpenAPI spec matches OAS3"""
+
+import argparse
+import sys
+
+from openapi_spec_validator import openapi_v3_spec_validator as validator
+import yaml
+
+failure = "\033[0;31m"
+success = "\033[0;32m"
+end = "\033[0m"
+
+
+def fetch_errors(errors):
+    """Return all the errors in the oapi spec with
+    some nice formatting for the terminal
+    """
+    num = len(errors)
+    pad = len(str(num))
+    err_ = [f"{num} problems with the spec:"]
+    for i, err in enumerate(errors):
+        msg, reason, loc = str(err).split("\n\n")
+        i = str(i).rjust(pad)
+        err_ += [
+            end
+            + f"{i}: {msg}\n{failure}{reason}\n{loc}".replace(
+                "\n", "\n" + " " * (2 + pad)
+            )
+        ]
+    return failure + "\n\n".join(err for err in err_) + end
+
+
+def validate(spec):
+    """a wrapper around the spec validator for our purposes"""
+    errors = list(validator.iter_errors(spec))
+    if errors:
+        error = fetch_errors(errors)
+        raise Exception(error)
+    else:
+        print(success + "No errors found in spec!" + end)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Check an OpenAPI yaml schema against OAS3"
+    )
+    parser.add_argument(
+        "api_spec",
+        help="path for the file to validate against.",
+        type=argparse.FileType("r"),
+    )
+    args = parser.parse_args()
+    with args.api_spec as f:
+        spec = yaml.load(f, Loader=yaml.FullLoader)
+    info = spec["info"]
+    print(f"Checking {info['title']} version {info['version']}")
+    validate(spec)
+
+
+if __name__ == "__main__":
+    sys.exit(main())