a8952c1f15
You can check the OpenAPI specification with:
$ rake linter:openapi
The integrated tools are:
spectral
redocly
openapi-format
They are all node.js programs. Spectral and Redocly are similar
tools, effectively two distinct openapi schema verifiers and heuristic
linting tools for openapi specifications. In the interest of getting
more coverage, I run them both.
openapi-format helps with ordering, indenting, etc the openapi YAML.
In particular, it is capable of alphabetizing paths, which makes it
much faster to bounce around similar parts of the API (e.g. everything
having to do with Postgres) via incremental search, without having to
micromanage exactly where new endpoints are inserted.
Because both `linter:openapi` and `linter:erb-formatter` modify source
code and I want to check if the git diff state is clean for both
tools, this check is consolidated and moved later in the CI process.
The specification has a long history, starting out closer to an
engineering pilot, but it looks like we'll adopt it into our
engineering. This patch falls short of doing that: there are still
some loose ends, but, it seems useful to integrate this segment first.
Burak Velioğlu wrote the first versions, to check if our API design
was going to drive its toolchain nuts or not. He did the first pass
over the API to make it more consistent and complete on the
implementation side as well.
Ben Satzger increased its robustness and completeness, to generate
some terraform provider code.
Having decided at this point that it was worth keeping the
specification up to date, I brought it into line with our tests, by
using the "committee" gem out-of-tree (so far).
Wesley a.k.a. @geemus, who told me about the some of the linting
infrastructure some time earlier, found some more streamlining
available to the specification, and tuned up our configuration of
those linters.
What comes next is integrating schema checking into our test suite.
There are some open problems with committee's included middleware
installed as-is, so, that has not been done yet. As such, this
specification will not remain perfectly up to date, yet.
Co-authored-by: Burak Velioğlu <bvelioglu@ubicloud.com>
Co-authored-by: Ben Satzger <ben@ubicloud.com>
Co-authored-by: Wesley Beary <geemus@gmail.com>
6 lines
95 B
YAML
6 lines
95 B
YAML
extends:
|
|
- recommended-strict
|
|
rules:
|
|
operation-4xx-response: off
|
|
no-ambiguous-paths: off
|