My company wants to migrate to API Dog but cannot do so since our current OpenAPI3 documentation contains callbacks which are crucial for our customers to have.
Additionally, we’d like to keep our components like parameters, headers and stuff to be linked instead of being documented each time we are creating a new endpoint.
For example, say we got this endpoint documentation with the openapi3 standard:
/examplecompany/mobile/predefined-order/new-customer:
post:
security:
- OAuth2ProdSchema: [predefined-order/new-customer]
- OAuth2PreProdSchema: [predefined-order/new-customer]
parameters:
- $ref: '#/components/parameters/x-usp-vo-id'
- $ref: '#/components/parameters/x-usp-originator-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PredefinedOrderSchema'
responses:
200:
$ref: '#/components/responses/OrderNewCustomer200'
callbacks:
onData:
'https://www.example.com/callback':
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewCustomerCallbackSchema'
responses:
'200':
description: OK
Importing this would clear the entire callbacks block and import the parameter schemas as standalone parameters for this request.
I think this should be handled to be openapi3 compatible. It should be possible to link parameters, headers (both of the parameters above are set to “in: header” so they are headers actually) and callbacks instead of creating them new every endpoint.
Neither do I find the option to specify callbacks in ui nor is it possible to add them to a yaml file manually.
For context: I removed the description and some responses to keep the char limit.