search

kadena-io / chainweb-data

Data ingestion for Chainweb.
BSD 3-Clause "New" or "Revised" License
14 stars 8 forks source link

Generate and serve OpenAPI specs #106

Closed enobayram closed 1 year ago

enobayram commented 1 year ago

This PR adds a hidden --serve-swagger-ui CLI option to the serve subcommand. When --serve-swagger-ui is enabled, chainweb-data serves an OpenAPI v3 spec for the chainweb-data API.

The spec that's currently served is automatically generated from the Servant API definition using servant-openapi3 and this PR makes no effort to refine the documentation generated by servant-openapi3 which lacks any explanations for the endpoints and the data schemas and it produces unhelpful details like integral values having meaningless upper and lower bounds.

So, despite being helpful as it is, the currently generated spec is only rudimentary, that's why this PR hides the new --serve-swagger-ui argument from the CLI --help output keeping it unofficial for now.

enobayram commented 1 year ago

Here's how I tested this PR:

I've started my CW-D instance with the --serve-swagger-ui option:

/nix/store/i9y1wln587zi8jac13mifms5i8qcgahi-chainweb-data-2.0.1/bin/chainweb-data --dbstring ... --level debug --service-host localhost --p2p-host localhost --p2p-port ... server --port ... --serve-swagger-ui

And went to $CWDURL/cwd-spec in my browser, which displayed the following page: image I've tried making a few request using the interactive documentation and I got back sensible results.

Then I tried starting the instance without --serve-swagger-ui, this time $CWDURL/cwd-spec responded with a 404:

$ curl $CWDURL/cwd-spec
Swagger UI server is not enabled on this instance