the start of a openapi spec for PIPs

[rrix]

go to https://petstore.swagger.io/ and replace the URL in the Explore box with: https://raw.githubusercontent.com/rrix/data-rights-protocol/main/openapi.yaml

This is the start of an openapi specification for the DRP protocol's PIP Interface. It's being provided here as step 1 in building out conformance testing for version 0.4 of the protocol, and will probably need to be kept in-sync with the existing markdown spec.

OpenAPI (F.K.A. swagger) is a machine-legible API specification standard that, in the simplest scenarios, can be used to test APIs in the Swagger web UI.

Further work:

• Exploring documenting the status callbacks through https://swagger.io/docs/specification/callbacks/
• Authentication (including OIDC support!) and feed that back in to the markdown spec

Limitations:

• there's no way to express parameter dependencies https://swagger.io/docs/specification/describing-parameters/#dependencies and so no way to express the specific set of allowable states in DataRequestStatus
• the payload of the identity token can't be expressed or created in the Swagger UI, it'd have to be constructed out of band, it's an opaque string (ping OAI/OpenAPI-Specification#1971) so this makes it un-ideal for test-case generation on its own.

[rrix]

There are schemaValidationMessages in the validator that I can't make heads or tails of right now. Maybe on Monday