Attaching Documents to an API
Pre-requisites:
You must have the Manage APIs functional privilege assigned to perform this task.
You can associate an input document that includes the RAML, Swagger, or WSDL specification, and additional documents such as programming guides, sample code, script files, and project plan with an API. For example, SOAP APIs can contain external documents such as Functional Requirements, Error Messages, Release Notes, and so on.
When attaching a document to an API, keep the following points in mind:
You cannot attach or modify a document to the API if it is in active state. You have to deactivate the API before attaching or modifying it.
API Gateway relies on file extensions to determine a file's type. When you upload a file from your local machine to the API, be sure the name of the file on your local machine includes a file extension so that
API Gateway can determine the file's type and attach it correctly to the API.
You cannot upload types of files that are restricted for attaching as the input document to the API.
API Gateway provides the ability to restrict certain kinds of files from being uploaded to the API, based on the file extension. The list of restricted files may vary depending on the file extensions configured in the apiDocumentsRestrictedExtension property under Administration > Extended settings section.
When you try to upload a file type that is restricted, API Gateway prompts you with an error message.
By default, several standard file extensions are blocked in
API Gateway, including any file extensions that are treated as executable files by Windows Explorer. The file extensions blocked by default are -
.bat,
.bin,
.dll, and
.exe.
You cannot upload files that exceed the maximum allowed size for the API.
API Gateway provides the ability to limit the maximum file upload size to the API. The maximum file upload size is configured in the apiDocumentsUploadSizeLimitInMB property under Administration > Extended settings section.
When you try to upload a file that exceeds the maximum file upload size, API Gateway prompts you with an error message.
You can rename an uploaded document. When you rename a document, you can only modify the display name of the document and not the document itself. If you want to modify the document as well, you must delete the file attachment, and attach the latest file.
To attach a document
1. Click APIs in the title navigation bar.
A list of all registered APIs appears.
2. Select the required API.
The API details page appears.
3. Click Edit.
4. Click Documentation.
5. Click Browse to select a file and upload it.
6. Rename the document in the Display name field as required.
This is the display name of the document in the API details page.
7. Click Add.
The attached document is listed in a table. You can edit and delete the document by clicking the
and
icons.
8. Repeat steps 5 to 7 for each document that you want to attach to the API.
9. Click Save.