search

nuts-foundation / nuts-node

The reference implementation of the Nuts specification. A decentralized identity network based on the w3c ssi concepts with practical functionality for the healthcare domain.
https://nuts-foundation.gitbook.io
GNU General Public License v3.0
23 stars 15 forks source link

Let OpenAPI specifications to be downloaded from Nuts Node #1102

Open reinkrul opened 2 years ago

reinkrul commented 2 years ago

This shouldn't be too hard; when you pass the spec option to openapi-codegen command, it adds the specification source to the generated code. Only thing left is to register some Echo routes to expose them.

jeroendee commented 2 years ago

Might be interesting to pick-up. Need more info though (as in, needs more refinement @reinkrul).

reinkrul commented 2 years ago

I actually did some initial work a while ago (https://github.com/nuts-foundation/nuts-node/pull/1115/files), but got stuck/went to more pressing matters when I came to resolving references inside OpenAPI specs to other OpenAPI documents. I resolved all conflicts so it's up-to-date with master again.

It lets engines expose their OpenAPI spec by implementing an interface, RouteSpec. Then the HTTP engine exposes it, e.g.: http://localhost/spec/vcr/v2. The spec is embedded by the codegen generator in the generated code. Which looks nice at first, but it is in JSON format, rather than the original YAML. As a consequence, references might not work, since they refer to YAML files rather than JSON files, e.g.: 

{
   ...
   "default":{"$ref":"../common/error_response.yaml"}}
   ...
}

Maybe better to use Go's file embedding functionality to just embed the literal YAML file, and serve them in the directory structure they're now in source. Because then the references keep working.

is spec the standard argument to use? Not sure, will need to be found out.

what does it mean when the "specification source" is added to the generated code?

The YAML file (which is now JSON in my linked PR).

what are Echo routes?

A route is a registered HTTP request, e.g. GET /some/path. Served by Echo, our HTTP server.