API Description Language Support
Information about the platform's support of API description languages for API documentation.
API Platform Version: 8.1 and later
Table of Contents
- What Swagger versions does the platform support?
- What Swagger support does the platform offer?
- Does the platform use any Swagger extensions?
- Does the platform support referencing of JSON schemas that are external to the API document definition?
- Does the platform support overloaded operations in API documentation?
- Are there any capabilities of the Swagger specification that the platform doesn't support?
- What RAML versions does the platform support?
- What features of the RAML specification does the platform support?
- Does the platform support including sample values for generated RAML documentation?
- Does the platform support the capabilities of the RAML 200 Tutorial?
- How can I view the API description document for an API?
- Does the platform support SOAP?
- Related Topics
What Swagger versions does the platform support?
The Akana Platform supports Swagger 1.2 and 2.0 along with Swagger-YAML.
The Akana API Platform user interface supports import of Swagger 2.0 and Swagger-YAML when adding a new API. However, it does not support upload of a Swagger 1.2 API description.
The underlying infrastructure supports creating an API by importing an API description document in either Swagger version, 1.2 or 2.0. You can use the Policy Manager console to load the Swagger 1.2 as a new service; then, you can use the Akana Platform user interface to add a new API and select the Publish an existing service as an API option.
What Swagger support does the platform offer?
The platform allows defining an API by uploading a Swagger description document. It also supports updating an existing API by uploading a Swagger description document.
Aspects of the API definition, such as parameters, request and response model objects, responses including HTTP codes and messages, and descriptive content are all supported.
The API documentation is generated dynamically for users.
Does the platform use any Swagger extensions?
Yes, the Akana API platform uses certain Swagger extensions to extend capabilities within the platform. These extensions are used internally and are not re-constituted when exporting an API description document.
In the underlying infrastructure, extensions are stored and reconstituted for the top-level Swagger object, operations, parameters, responses, and schema, regardless of whether the extension is external or internal.
Does the platform support overloaded operations in API documentation?
The platform supports adding overloaded operations (multiple operations using the same path, with different design elements such as media types), and displays overloaded operations correctly in the user interface, including API pages, generated API documentation, and Test Client.
The Swagger 2.0 standard specification does not support overloaded operations; because of this, if you try to download a Swagger document (API > Details > Implementations (bottom of page) for an API that includes overloaded operations, the platform generates an error. This is also true for Swagger 1.2 and RAML. Overloaded operations are not an issue with WADL.
Does the platform support referencing of JSON schemas that are external to the API document definition?
No; all JSON schemas must be defined as part of the API description document, without the need for any additional external information. Referenced external schemas are not currently supported.
The platform supports referencing of JSON schemas in these scenarios:
- Schemas referenced in the same RAML file
- Inline schemas
Are there any capabilities of the Swagger specification that the platform doesn't support?
The platform currently has no support or limited support for these capabilities of the Swagger 2.0 specification (http://swagger.io/specification/):
- Global Parameters
The API Platform does not support the use of global parameters in Swagger 2.0, and neither does the underlying infrastructure.
- Includes ($ref fields)
In the API platform, includes are ignored, including references to schema documents.
In the underlying infrastructure, upload is supported only for a single file. However, you can include referenced documents along with the root document by including multiple files in a single ZIP file (uploaded locally, or retrieved from an external URL).
The Swagger 2.0 specification supports including sample values in Swagger documentation; however, the Akana API Platform doesn't currently support this feature.
The underlying infrastructure supports including examples in Swagger for parameters, but not for operations. In the API platform, examples are ignored, and are not displayed in the API Designer or in generated documentation.
What RAML versions does the platform support?
The Akana API platform supports the following RAML versions:
What features of the RAML specification does the platform support?
The Akana platform supports the core features of the RAML specification, as referenced in the RAML 100 Tutorial (http://raml.org/developers/raml-100-tutorial), except examples.
- URI parameters
- Query parameters
The platform doesn't yet support including examples in the generated documentation. Examples for query parameters, request body, or response body are not represented in the Akana API Designer and are omitted when exporting to Swagger, WSDL, or WADL
Does the platform support including sample values for generated RAML documentation?
The RAML 0.8 specification support including a sample request in RAML documentation; however, the Akana API Platform currently does not support this feature.
The underlying infrastructure supports including examples for parameters in RAML, but not for operations.
Does the platform support the capabilities of the RAML 200 Tutorial?
The RAML 200 tutorial (http://raml.org/developers/raml-200-tutorial) demonstrates more complex capabilities of RAML, including:
- Body parameters
- Form parameters
Includes: If you're uploading a single RAML file that has includes, either from a URL or from the local filesystem, the platform generates an error on import. However, you can include referenced documents along with the root document by including multiple files in a single ZIP file (uploaded locally, or retrieved from an external URL).
Some of the capabilities covered by the RAML 200 tutorial are not yet supported by the Akana API platform, including:
- Traits: If you import a RAML file with Traits, the platform generates an error when trying to view the API in the API Designer.
- RAML Specification Parameters: If you import a RAML file with Specification Parameters, no errors are generated but the Specification Parameters are ignored.
- Resource Types: If you import a RAML file with Resource Types, the platform gives an error when trying to view the API in the API Designer.
- External Schemas: the platform supports schemas referenced in the same RAML file and inline schemas, but does not support schemas referenced in an external file. The import fails.
How can I view the API description document for an API?
The API Admin can view the visual design of the API in API Designer, and can also view the Swagger representation by clicking the Swagger tab: see How do I view the Swagger representation of my API in API Designer?
If you're not the Admin for the API, or if you want to view the API description in some other format—for example, the API is based on Swagger but you want to view a RAML or WADL representation—you can do that in the Implementations section:
- All users who have view access to the API: on the API's Overview page, in the Implementations section.
- API Admins: The same information is also on the API's Details page.
In most cases, you can view a representation of the API in all supported description languages, as shown below:
Note: For SOAP-based APIs, created by uploading a WSDL file, only the WSDL option is available. See How do I add a SOAP-based API?
In the above example, the API can be viewed in all formats supported by the API Platform:
- Swagger 2.0
- Swagger 1.2
To view the API representation, click the applicable icon. The API description is immediately available:
- For Swagger 1.2, Swagger 2.0, and WSDL, the API description document opens in a new browser tab.
- For RAML and WADL, the API description is available as a downloaded file.
Does the platform support SOAP?
Yes. You can create a SOAP-based API on the developer portal by importing the WSDL file for the API. See How do I add a SOAP-based API?
If your API is SOAP-based, you can't modify it using the API Designer; however, you can update the API by uploading a new WSDL file.
In general, although the developer portal supports viewing the API description document for REST-based APIs in different formats, such as Swagger 2.0 or RAML, a SOAP-based API cannot be viewed in other API description formats. You can only view the WSDL. See How do I add a SOAP-based API?