Skip to main content

OpenAPI/Swagger External Documentation Now Supported in API Transformer

· One min read

OpenAPI/Swagger allows you to include external documentation in your API description for various components. API Transformer now supports conversion of this information for both import/export of OpenAPI/Swagger files.

Details​

OpenAPI/Swagger allows you to link external documentation at four different levels in your API description:

  1. Root Object [v2.0, v3.0]
  2. Operation Object [v2.0, v3.0]
  3. Tag Object [v2.0, v3.0]
  4. Schema Object [v2.0, v3.0]

For each of the above levels, you can define an External Documentation Object against the externalDocs property. It can look like the following:

{   
    "externalDocs": {
      "description": "More details can be found at:",
      "url": "https://example.com"
    }
}

For External Documentation Object to be considered valid and transformed successfully, url must be present as it is a required property.