Managing OpenAPI documents
3 minute read
OpenAPI specification support
Currently, OpenAPI flow-trigger supports the following specifications:
If you do not already have an OpenAPI specification to manage, you can read our guide on how to write OpenAPI documents.
Importing OpenAPI documents
You can import OpenAPI documents from the API Doc & Test page. Note that OpenAPI 2.0 and OpenAPI 3.0 are supported, but that OpenAPI 3.0 is the preferred standard for API Builder. Please see OpenAPI specification support for further details on the OpenAPI standards and their supported features.
Once loaded, you can update or delete the document as required.
Binding OpenAPI operations
The Quick start shows how to bind OpenAPI operations flows. When operations are bound, updating the OpenAPI document subsequently can affect bound operations.
Updating OpenAPI documents
Before updating your OpenAPI document, you should first be aware of how API Builder uses it, and what impact your changes might have. The main differentiator between “safe” and “unsafe” changes are whether or not an OpenAPI operation is not bound to a flow or not, or if the item being changed is related to a bound OpenAPI operation.
The details in the following sections are only relevant if operations are bound to flows. If operations are not bound to flows, you can update them without any affect.
Changing a bound operationId
Changing the name of a bound operation’s operationId is the same as deleting it and adding a new one with a new name. It is impossible to distinguish. When this happens, the old operation and flow will become unbound. To fix, edit the flow, and change the OpenAPI flow-trigger Method to use the new operationId.
Removing a bound operation
This is an unsafe update. If you remove an OpenAPI operation that is bound to a flow, the flow will become “unbound”, and the console window and UI will show an error that this happened. If you have no need of the flow, it is safe to delete.
Changing method, path, or path parameter of a bound operation
If your operation does not use an operationId, then changing the method, path, or path parameters of a bound operation is the same as removing a bound operation. This is discussed in the writing OpenAPI documents on how to manage your API more effectively. However, if your operation does use an operationId, then it is shielded against this.
Changes that may break a flow
In addition to directly manipulating the method, path, or path parameters of an Operation object, the following changes may break your flow and require additional changes in the flow editor.
- Removing parameters
- Renaming parameters (this is effectively removing them)
- Changing parameter names (even capitalization)
- Changing the request
- Changing the response content-type or schema
- Removing responses
Deleting OpenAPI documents
Deleting your OpenAPI documents is an action that should be taken with caution. It is an irreversible action that can have a big impact on your service as you are removing the OpenAPI document and all associated flows from it. Any unrelated flows will be preserved.
