Improve swagger UI

[nrempel]

Default is not great.

Redoc looks good but lacks interactive console: https://github.com/Redocly/redoc/issues/53

Some relevant info: https://stackoverflow.com/questions/36634281/list-of-swagger-ui-alternatives/41273860#41273860

[swcurran]

The use case is the same as for Swagger -- teaching developers to use the API for developing a controller. That includes using it in workhops and in docs like this one: https://github.com/hyperledger/aries-cloudagent-python/blob/master/demo/AriesOpenAPIDemo.md and this one: https://github.com/hyperledger/aries-cloudagent-python/blob/master/demo/AriesOpenAPIDemo-mobile.md

[nrempel]

One of the best options I've seen so far are to import the swagger json definition into a tool like Insomnia or Postman and use that for testing.

Another option that I've come across is this one: https://github.com/mulesoft/api-console

It appears to ingest both RAML and OAS (Swagger) definitions and create an interactive console out of them. I ran the demo and it seems pretty good. You can try it out by going here and following the instructions (just 3 commands).

https://github.com/mulesoft/api-console#preview-and-development

The one thing is that isn't clear to me yet is how to configure it to use a swagger definition. It seems like you can't just point it at a definition url, it needs to converted into something called an AMF definition and then fed through their AMF parser. This seems like a bit of unnecessary complexity, but it should be something we can automate if the UI is worth it.

[ianco]

Are there specific issues with the current swagger page?

[swcurran]

The UI for it sucks. Other than that, no :-). I'm just wondering if there is a way to provide a nicer experience.

[swcurran]

Looks like there is a docker image for the Mulesoft api-console.

https://docs.api-console.io/building/docker/

Example is this:

docker run  \
  -v "$PWD":/app/api \
  -e API_PROJECT="api.raml" \
  -e API_TYPE="RAML 1.0" \
  -e API_MIME="application/raml" \
  gcr.io/api-console-a6952/app:0.1.0

So we should be able to do this. However, I'm not sure how to get the ACA-Py (or Aries VCR) Swagger definition file. Where is it?

docker run  \
  -v "$PWD":/app/api \
  -e API_PROJECT="acapy_swagger.json" \
  -e API_TYPE="OAS 3.0" \
  -e API_MIME="application/json" \
  gcr.io/api-console-a6952/app:0.1.0

I'd like to see what it looks like, but they don't make it easy...

Would we build it into the apps (agent and VCR)?

[WadeBarnes]

@swcurran, /api/?format=openapi, example; https://orgbook-dev.pathfinder.gov.bc.ca/api/?format=openapi

[swcurran]

Thanks - got it working. The downloaded file is evidently an OAS 2.0 file. I had to edit the file and remove the security entry to run it. The UI is nicer. Not that much nicer, but better in that the list in the right side menu is more concise.

Here is how to run it in docker on port 5000 if you want to try it:

curl https://orgbook-dev.pathfinder.gov.bc.ca/api/?format=openapi -o api.json
sed  "s/{\"basic\": \[\]}//" api.json >orgBookAPI.json
docker run    -v "$PWD":/app/api   -e API_PROJECT="orgbookAPI.json" -p 5000:8080  -e API_TYPE="OAS 2.0"   -e API_MIME="application/json"   gcr.io/
api-console-a6952/app:0.1.0

Should I just give up?

[nrempel]

Have you tried insomnia? Pretty easy to get going, hit "import workspace" or something and give it the swagger definition url and that's it.

[swcurran]

I'm looking for an embedded UI so the user doesn't have to do anything. The concept of Swagger is ideal, it's just the UI.

I'll shut this done - we've looked at it enough. Swagger is the standard, so we'll have to go with it. I'm just suprised there isn't anything better.

Thanks!

[nrempel]

Sounds good. Last thought - does the open data BC thing provide a nice interface?

[swcurran]

That would only help for OrgBook, and I'm looking for ACA-Py in particular.