Created experimental Open API Specification plugin for ReSpec

Hi all,

I've been playing around with an Open API Specification (OAS) plugin for
ReSpec (respec-oas) as a part of the W3C Credentials Community Group's work on
the Verifiable Credentials HTTP API.

The plugin basically takes an OAS file and can render portions of that file
(API summary tables, HTTP response codes and their explanations, JSON Schema
for HTTP API POST data, etc.) in a way that ReSpec can post-process.

Controversially, the plugin can also auto-generate normative statements
straight from the JSON Schema. An example of the plugin's current output can
be found here (the entirety of this section, including all normative
statements, are auto-generated):

https://w3c-ccg.github.io/vc-api/#issue-credential

Some part of this feels as if it (auto-generated normative statements) is an
abomination -- just think about all the spec writers that we're going to put
out of a job! The Spec Writers Union is going to protest! :P

Another part of this feels like it's a workable direction. A number of
implementers in the VC API group desperately want the source of truth to be
the JSON Schema files (yet, JSON Schema is not flexible enough to express all
of the normative statements we'd need to make in the specification). So, the
challenge was enabling JSON Schema to be /some form of truth/ while enabling
the spec to include those truths and add its own truths on top.

HTTP API summary tables are generated like so:

https://github.com/w3c-ccg/vc-api/blob/main/index.html#L479-L481

API endpoint details are generated like so:

https://github.com/w3c-ccg/vc-api/blob/main/index.html#L488-L489

All of that is generated from the OAS source here:

https://github.com/w3c-ccg/vc-api/blob/main/issuer.yml#L13-L36

The OAS file is linted by the ReSpec loader, so you always know if your OAS
file is conformant (and renderable) or not.

Still lots of issues to work through, and this is very much a work in
progress, but am putting this out there early in case others are working on
something similar or have a need for something like respec-oas.

Concerns, comments, suggestions are very welcome as I don't know if any other
CGs/WGs are working on HTTP APIs?

-- manu

-- 
Manu Sporny - https://www.linkedin.com/in/manusporny/
Founder/CEO - Digital Bazaar, Inc.
News: Digital Bazaar Announces New Case Studies (2021)
https://www.digitalbazaar.com/

Received on Monday, 18 April 2022 15:30:09 UTC