WIP: Use specs to write an openapi3 spec

[segiddins]

Please do not review this.

Just sharing the code I'm using to slowly write an openapi3 doc for the v1 API.

Workflow has been:

Run a single controllers tests. Add missing paths / operations. Ensure that request / response bodies match the spec.

Will look into better tooling for this sort of test that will work for both system & functional tests, and also doesn't require rspec. Stay tuned.

[codecov]

Codecov Report

Merging #3896 (a9ed0b5) into master (5ec5af4) will decrease coverage by 4.61%.
The diff coverage is 67.85%.

@@            Coverage Diff             @@
##           master    #3896      +/-   ##
==========================================
- Coverage   98.79%   94.18%   -4.61%     
==========================================
  Files         216      217       +1     
  Lines        5391     5419      +28     
==========================================
- Hits         5326     5104     -222     
- Misses         65      315     +250     

Impacted Files	Coverage Δ
app/controllers/api/v1/schema_controller.rb	0.00% <0.00%> (ø)
app/controllers/api/base_controller.rb	92.30% <100.00%> (-7.70%)	⬇️

... and 18 files with indirect coverage changes