Adding a REST API by using a Swagger file

If a REST API owner provides you with the details of the API in a Swagger file, you can use the Swagger file to add the REST API. You can also provide a URL link to a location from which you can obtain the Swagger definition.

Before you begin

Your file must conform to version 2.0 of the Swagger specification. The format of the file can be JSON or YAML.

Important: To be accessible by IBM® API Management on Cloud, the services that you expose must be visible on the internet, they must not be accessible only from within your corporate intranet. However, you can use SSL profiles configured in API Manager to protect the communication channel between the API Gateway in API Management and the services that you expose on the internet through your DMZ.

To complete the API management tasks described in this topic, you must either be the owner of the API provider organization, or be assigned a role that has permission to edit draft APIs. If you have permission only to view draft APIs, you cannot create, edit, or delete APIs. For information on managing user roles, see Administering user access.

Procedure

To add a REST API by loading a Swagger file, complete the following steps:

  1. In the navigation section of API Manager, click the APIs icon The APIs icon. The APIs page opens.
  2. Click + API, and select Import Swagger. The Add API From Swagger Definition dialog box opens.
  3. Select the Load a Swagger File tab.
  4. You can upload the Swagger file by using either of the following options:
    • Click Select a File and browse for the file.
    • In the Load from URL section, complete the Swagger URL field. If the URL is secured, you must provide the user name and password for accessing the URL. Then click Load.
    All of the methods that are contained in the Swagger file are displayed.
  5. Click Add. A new REST API is created, and the methods are added to the API as operations.

When the operation is complete, the REST API is shown in the APIs list.

  1. Optional: Add one or more categories to your API for ease of grouping in the API Manager user interface. To categorize your API, click + Category. You can choose the default Favorite category or you can create your own by entering a name into the Create new category field. These categories are simple labels that you can use to organize and search for APIs. To quickly display all the APIs with the same category, you can select the category name in the Categories list displayed in the side pane, or select No category to display APIs that have not been categorized.
  2. Optional: Add Swagger extensions to your API by completing the following steps:
    1. If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Extensions section, and enter the JSON code for your extensions in the field provided.
    3. Click Apply, then click Save.
    For more information, see Defining Swagger extensions for a REST API.
  3. Optional: Provide additional information for your API by completing the following steps:
    1. If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Additional Information section, and enter information in the Contact, License, and Terms of Service panes as required.
    3. To add Swagger extensions to the additional information, click the Define extensions icon Define extensions icon. For more information, see Defining Swagger extensions for a REST API.
    If you download the Swagger file for the API, the additional information is written to the info field.
  4. Optional: Provide external documentation information for your API by completing the following steps:
    1. If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Additional Information section, and enter information in the External Documentation pane as required.
    If you download the Swagger file for the API, the additional information is written to the externalDocs field.
  5. Optional: Declare one or more tags for your API; these tags can then be applied to the operations in the API. Operation tags are labels that can be used by application developers to organize and search for operations in the Developer Portal. To declare a tag for your API, complete the following steps:
    1. If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Tags section, and click + Tag.
    3. Enter a name and description for the tag.
    4. To add Swagger extensions to the tag, click the Define extensions icon Define extensions icon. For more information, see Defining Swagger extensions for a REST API.
  6. Optional: Specify the implementation phase of your API by completing the following steps:
    1. If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Settings section, and select one of the following values from the Phase list:
      Identified

      The API is in the early conceptual phase and is neither fully designed nor implemented.

      Specified

      The API has been fully designed and passed an internal milestone but has not yet been implemented.

      Realized

      The API is in the implementation phase.

      For a REST API, if you download the Swagger file for the API, the information is written to the phase field.
  7. Optional: If your API is in the Realized phase, specify the enforcement options for your API by completing the following steps:
    1. Note: Unenforced APIs will not be documented correctly or testable in the Basic Developer Portal, however, they will work correctly in the Advanced Developer Portal.
      If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Settings section.
    3. If your API will be enforced by a gateway other than IBM API Management, clear the Enforce this API check box. Use the Base Path, Hostname, and Schemes fields to define the endpoint URL for the API.
    4. If you do not want to allow your API to be tested in the developer portal, clear the Allow this API to be tested check box.

    For a REST API, if you download the Swagger file for the API, the information is written to the enforced and testable fields.

    If your API is in the Realized phase, and it will be enforced by a gateway other than IBM API Management, any implementation or load balancer endpoints that you define are advertised in the developer portal, and there are no API proxy or API assembly defined endpoints.

    If your API is in the Realized phase, and it will be enforced by the IBM API Management gateway, it has an implementation endpoint and, optionally, a load balancer endpoint that is advertised in the developer portal, together with API proxy or API assembly defined endpoints.

    Note: You cannot specify enforcement options unless your API is in the Realized phase.
  8. Optional: If your API will be enforced by a gateway other than IBM API Management, specify the host name and transfer protocols for your API by completing the following steps:
    1. If the API details are not already displayed, expand the required API, and click the API revision that you want to work with.
    2. Expand the Settings section, enter the host name, and select the required protocols alongside the Schemes label. You can select from the following options:
      • http
      • https
      • ws
      • wss
      For a REST API, if you download the Swagger file for the API, the information is written to the host and schemes fields.
      Note: If your API is enforced by the IBM API Management gateway, only the HTTPS protocol is supported.
  9. Optional: To upload a file or provide a URL that gives additional documentation about the API, complete the following steps.
    1. Click the API that you want to work with to display the API details.
    2. Select the Documentation tab
    3. Click + Documentation and Attachments, and complete one of the following steps:
      • Click Upload File, select the required documentation file, and click Open.
      • Enter a URL location for the file.
    4. Enter a display name and, optionally, a description, then click Add. The uploaded file is attached to the API.
    If the API is added to the Developer Portal, the documentation is displayed with the API.
    Note: If your administrator has restricted the extensions of the files that you are allowed to upload, you can upload a file only if it has one of the supported file extensions; an error is returned if the file extension is not supported.

What to do next

To finish the creation of your API, complete the following tasks.






Timestamp icon Last updated: Monday, November 23, 2015