@Yousaf Nabi (pactflow.io) (cc: @Matt (pactflow.io / pact-js / pact-go))

The Pact Broker API docs (outside of the HAL Browser) are woefully lacking. I would love this year to be the year we turn this around.

I’ve made a start on some auto generated markdown docs for some of the more popular endpoints.

I don’t see this as the final format - just the easiest thing I can do to get things started.

My approach is to have a test that generates a JSON fixture with an example of the request and response. This interaction data could then be post processed into anything we like. At the moment, I’ve just gone with markdown, but ideally we’d be able to support an OAS doc. I’m not sure if we’d go with a custom OAS and procedural verification, or an auto generated OAS.

Example documentation spec: https://github.com/pact-foundation/pact_broker/blob/master/spec/integration/pacticipants_documentation_spec.rb

Generated JSON fixture: https://github.com/pact-foundation/pact_broker/blob/master/spec/fixtures/approvals/docs_pacticipants_pacticipant_put.approved.json