OpenAPI Specification Contracts
Providers may specify an OpenAPI Specification as a Provider Contract, enabling teams to reuse existing tools and processes.
Supported versionsβ
Version | Supported? |
---|---|
Swagger (1.x) | β |
Swagger (2.0) | β |
OAS 3.0.x (up to 3.0.3) | β |
OAS 3.1.x (up to 3.1.0) | β |
Limitations and Considerationsβ
PactFlow transforms your OASβ
PactFlow needs to perform a number of minor modifications to the document prior to validation to perform its compatibility checks and support many OAS features. In most cases, they will be transparent to you. You can find more information here.
Document Limitationsβ
When using the OpenAPI Specifications as a Provider Contract, you should know the following limitations.
- The OAS must be a valid YAML or JSON file. PactFlow will give an error if an invalid document is provided.
- OAS documents must not be split across multiple files. You should combine the documents together, using tools like OpenAPI Merge or speccy. That is, PactFlow can not resolve remote references to files, and will not resolve URL references.
- YAML formatted OAS documents must not use anchors, due to the potential security issues (see YAML bomb for more). If your auto-generated specs have anchors, you can pre-process them via tools like spruce, that will expand them for you.
Other Considerationsβ
- It is recommended to set
additionalProperties
totrue
on request items to align with Postel's Law. - Implementing a spec is not the same as being compatible with a spec (read more). Most tools only tell you that what youβre doing is not incompatible with the spec.
- You are responsible for ensuring sufficient OAS coverage. To highlight this point, in our Dredd example, we do not test the 404 case on the provider, but the consumer has a pact for it and its tests still pass! NOTE: We plan to address this problem in the future via our OAS Testing Tool.