Bundle VC-API and provide UX on API Docs #270
Conversation
mprorock
requested review from
peacekeeper,
msporny,
mavarley,
OR13 and
mkhraisha
as code owners
There was a problem hiding this comment.
Overall, +1 to the direction of this PR and looking forward to merging it in.
Two concrete change suggestions:
- We shouldn't be checking in files that are auto-generated and/or duplicate content we already have - everything in /api/* seems to be auto-generated as a part of the build process, can we get rid of those and push the generation to build time/the workflows script?
- Same for package-lock.json file -- this isn't production software yet, no need to lock versions in -- we want builds to break to keep pace w/ latest packages... we can lock this in when this stuff goes to REC.
We should link to the auto-generated docs from the main spec header, like we do in DID Core -- see "Related Documents": https://www.w3.org/TR/did-core/
+1 to both of these - wanted to at least give folks the ability to see the generated in the event they aren't used to bundling multiple spec definitions have pushed appropriate changes to gitignore, etc and folks can ref commits prior to this comment if they want to see or pull down a generated file to test |
yep - that is definitely the idea - I think lets get this in first, then get a CI PR that handles builds and push to gh-pages the way we want it (i.e. deploy both spec itself as well as api docs) - then adjust README and spec to point correctly to final locations |
| - `api/vc-api.yaml` a master file with all specifications rolled into one | ||
| - `api/bundles/issuer.yml` issuer endpoints bundled with no external refs | ||
| - `api/bundles/verifier.yml` verifier endpoints bundled with no external refs | ||
| - `api/bundles/holder.yml` holder endpoints bundled with no external refs |
There was a problem hiding this comment.
| - `api/vc-api.yaml` a master file with all specifications rolled into one | |
| - `api/bundles/issuer.yml` issuer endpoints bundled with no external refs | |
| - `api/bundles/verifier.yml` verifier endpoints bundled with no external refs | |
| - `api/bundles/holder.yml` holder endpoints bundled with no external refs | |
| - `api/vc-api.yaml` — a master file with all specifications rolled into one | |
| - `api/bundles/issuer.yml` — issuer endpoints bundled with no external refs | |
| - `api/bundles/verifier.yml` — verifier endpoints bundled with no external refs | |
| - `api/bundles/holder.yml` — holder endpoints bundled with no external refs |
There was a problem hiding this comment.
I don't have the ability to accept this change (don't have access to @mprorock's repo). I will put this change in right after I merge.
bundles up the openapi specs, and provides the ability for developers to cleanly generate stubs from a variety of tools for:
additionally provides the ability for developers to use their doc interface of choice as raw swagger can be painful.
NB: several rooms for improvement areas, such as proper tag names, etc for the docs, but those should be discussed as a group