plutus-pab: Adds Swagger support for web-server API

[kelizarov]

This change adds a support for swagger using servant-openapi that generates an OpenAPI spec for PAB API with descriptions to provide a non-technical information for how endpoints behave and what they expect in requests and responses.

The swagger-ui is accessible through swagger/swagger-ui/index.html
The example of UI:

Pre-submit checklist:

• Branch
  • Tests are provided (if possible)
  • Commit sequence broadly makes sense
  • Key commits have useful messages
  • Relevant tickets are mentioned in commit messages
  • Formatting, materialized Nix files, PNG optimization, etc. are updated
• PR
  • Self-reviewed the diff
  • Useful pull request description
  • Reviewer requested

[nau]

You need to run ./updateMaterialized inside nix-shell to update nix files.

[goosedb]

@nau done!

[j-mueller]

Making the API self-describing is generally very useful and will make it much easier to generate clients in other languages. We looked at swagger a while ago and the issue that prevented us from using it was lack of support for sum types. But it looks like a new major version of swagger/open API is out so maybe it's time to revisit this.

How does OpenAPI3 handle sum types? For example what does the schema for UniswapContracts look like?

[kelizarov]

Hey @j-mueller the servant-openapi adds support for Sum types by using oneOf construction. I've fired up Uniswap PAB instance with these changes, here's how the model looks like in swagger-ui:

[kelizarov]

There's also an issue with representing tuple types in swagger. For example for txRedeemers in Tx type it represented like this:

The simple solution could be to declare the ToSchema instance manually instead of using the generic deriviation. Let me know if this is critical here.

[j-mueller]

The oneOf construct looks nice, so I'm happy to accept this now.

issue with representing tuple types in swagger

Sorry what is the issue exactly? That the types of the elements of the list aren't specified? In general, encoding a tuple as a heterogeneous list with a fixed length is fine (that is what a tuple is, and that's the default encoding that aeson uses)

[michaelpj]

This PR adds package dependencies to plutus-ledger which are not used, and that's what Hydra complains about: https://github.com/input-output-hk/plutus/pull/3807/files#diff-cb3369701745e982609f4dfe004aa53507b8570ddc9841d1aa4f186109c32725R122-R123

[michaelpj]

I don't think we should add a dependency on openapi to the packages below plutus-ledger-api. Those are depended on by the node, and I don't think we want this in the dependency tree for that. You could put them in your orphans module, perhaps.

[kelizarov]

This PR adds package dependencies to plutus-ledger which are not used, and that's what Hydra complains about: https://github.com/input-output-hk/plutus/pull/3807/files#diff-cb3369701745e982609f4dfe004aa53507b8570ddc9841d1aa4f186109c32725R122-R123

But they're used in these module:
https://github.com/input-output-hk/plutus/pull/3807/files#diff-3792e47803463e7e1b312bd15a54ff370e386fb431ac1d03fb3f68b8bb65c648
https://github.com/input-output-hk/plutus/pull/3807/files#diff-dad89552434f03995ef455b89ec062dd4cc79caf69faf09aeb2ab70d1417cb7b

Is there some other way to include dependencies to packages?

[michaelpj]

No they aren't. You added freer-simple, semigroups, and openapi3, and you're only using openapi3. Which is exactly what the error message said.

[kelizarov]

@j-mueller @michaelpj I've added the changes for orphan instances: put them on plutus-ledger package and removed openapi3 dependency from plutus-ledger-api and plutus-core.

[Fiftyw3bs]

I think the merging of this PR has taken enough time.

I'm stuck at ToSchema not accepting Sum types. This PR seems to be the only block standing in my way ;(

[j-mueller]

I'd like to get a second opinion from @silky before merging, but it looks good to me now.

[silky]

Looks great to me! Thanks for doing this work. I've added a couple of small suggestions, then I'm happy to merge!

[silky]

Hey @kelizarov - All looks great; just one final thing ( I promise! sorry :) ) - If you can rebase to master and squish a few of the commits down so the history is a bit cleaner that would be perfect!

[michaelpj]

@silky you can also just do a squash-merge if you like

[silky]

Ah thanks @michaelpj ; I looked at 'rebase and merge; only :)
I'll do that!

-- Edit: Thanks @kelizarov for your work on this!

[michaelpj]

I don't think we should add a dependency on openapi to the packages below plutus-ledger-api. Those are depended on by the node, and I don't think we want this in the dependency tree for that.

This PR still adds a dependency on openapi to plutus-tx, which I said we shouldn't do. @silky can you please move those instances to the orphans module and get rid of the dependency?

[Fiftyw3bs]

Hi @michaelpj

May I ask how this affects the developers waiting to make use of the solutions in this PR? I, for one, have been stuck for like a week waiting for it to be merged.

[michaelpj]

It shouldn't affect you. I have generously decided not to revert it and instead to let it be fixed in a subsequent PR :)