plutus-chain-index swagger documentation isn't complete and/or rendering correctly

[ross-spencer]

Summary

Swagger/OpenAPI documenation is supposed to be interactive and offer the user a way into an API. Currently, a number of endpoints in the plutus-chain-index docs are incomplete and it is difficult/impossible for a new user to access these and find the right way into the endpoints.

Take for example this naive use of the tx endpoint:

Steps to reproduce the behavior

On the command line the result looks as follows:

curl -X 'POST' 'http://xxx.xxx.xxx.xxx:9084/tx'  \
 -H 'accept: application/json;charset=utf-8'   \
 -H 'Content-Type: application/json;charset=utf-8'   \
 -d '"27b46f95470d82b88e7a91429ed3b7c3c14c151223289f5510e72598678a5b0b"'

Actual Result

Error in $: parsing Plutus.V1.Ledger.Tx.TxId(TxId) failed, expected Object, but encountered String

Expected Result

A valid request can be built for any endpoint on the chain-index API and it will return something sensible.

Thanks to this Cardano stack exchange post, we have a way forward for this endpoint: https://cardano.stackexchange.com/questions/7714/how-to-query-the-chain-index-tx-endpoint

e.g.

curl -X 'POST' \
  'http://xxx.xxx.xxx.xxx:9084/tx' \
  -H 'accept: application/json;charset=utf-8' \
  -H 'Content-Type: application/json;charset=utf-8' \
  -d '{"getTxId" : "27b46f95470d82b88e7a91429ed3b7c3c14c151223289f5510e72598678a5b0b"}'

This successfully returns transaction information on preprod.

Connected to: #130
Connected to #652
Connected to #651
Connected to #4

Describe the approach you would take to fix this

Add the documentation to the endpoints where there is none. The example value/schema portion of the endpoint needs to be complete and accurate. Not just "string" as this can't be reverse engineered by anyone.

An annotated error response from plutus may also be amended to describe the expected schema, i.e. when is seeks an object, what does the object look like.

Error in $: parsing Plutus.V1.Ledger.Tx.TxId(TxId) failed, expected Object, but encountered String

Could be:

Error in $: parsing Plutus.V1.Ledger.Tx.TxId(TxId) failed, expected Object of type {"getTxId": "acdc1234"}, but encountered String

NB. Not a plutus developer, so this latter part may be out of anyone's control.

System info

Unsure as to which plutus-chain-index is being used as I am not sure version is available from the command line options.

[ross-spencer]

NB. between the POST verb here, and the JSON (getTxId) there's some confusion in verbage. I don't know what scope there is to fix that kind of thing, but if that's worthy of another ticket, we can make that. It will be easier to analyse the different schema once it's more visible.

curl -X 'POST' \
  'http://xxx.xxx.xxx.xxx:9084/tx' \
  -H 'accept: application/json;charset=utf-8' \
  -H 'Content-Type: application/json;charset=utf-8' \
  -d '{"getTxId" : "27b46f95470d82b88e7a91429ed3b7c3c14c151223289f5510e72598678a5b0b"}'