Documentation-Driven Contracts

Documentation-Driven Contracts are another service evolution pattern that may be more appropriate for public APIs or other providers that many consumers. Since establishing a separate contract for each consumer is not practical, the next best thing is to have ensure the documentation accurate reflects the promises made by the service.

In Documentation-Driven Contracts you want to make your documentation the source of truth for the contract. Good documentation formats are apiblueprint (used by apiary.io), swagger, or WADL (used by Apigee and others).

We want to take those documentation formats:

  • Create contracts based on the documented structure
  • Create sample requests for simulated consumers to test providers
  • Create stubbed responses to test consumers

Pacto does not yet have support for generating a Contract from documentation, but it is on our roadmap. We will likely start with apiblueprint.