Creating and modifying I/O Doc in Control Center

Cloud API Management (Control Center) administrators can create and manage I/O Docs on the Control Center's Interactive Documentation page.

Before you begin

Before creating an I/O Doc on Control Center, you must ensure the following:

• You have access to the Cloud API Management with API Manager or Administrator permissions to create and manage I/O Docs.

• You have at least one API definition with a resource endpoint configured as a GraphQL endpoint on Control Center.

Creating an I/O Doc

Procedure

1. Navigate to Design > Interactive Documentation. This opens the Interactive Documentation page.

2. Click New Interactive Documentation. The New Interactive Documentation pop-up window opens.

   1. In API Definition, select an API definition for which you have created an endpoint.

   2. In Select API Type, select OpenAPI, IO Doc, or GraphQL to create an Interactive Documentation.

      note

      The selected API type cannot be changed later once interactive documentation is saved.

      1. If you selected OpenAPI API Type:

         1. Click Choose file to upload a JSON or YAML schema file in OpenAPI specification format. The built-in validator checks the uploaded JSON file; if the schema is invalid, the changes are not saved.

            Or

         2. In Import from URI, enter the URI to import a specification file.

      2. If you selected IO Doc API Type:

         note

         For OpenAPI API definitions, one item covers all endpoints, so only one Interactive Documentation item is allowed per API definition.

         1. Click Choose file to upload a JSON or YAML schema file in OpenAPI specification format. The built-in validator checks the uploaded JSON file; if the schema is invalid, the changes are not saved.

            Or

         2. In Link to a WSDL file, enter the link to the WSDL file for SOAP-based APIs.

            note

            Ensure that the WSDL is valid. If the WSDL is invalid or non-compliant with the requirements, the changes are not saved. Refer to the WSDL import for SOAP APIs for more information on using WSDL.

      3. If you selected GraphQL API Type:

         important

         • Before creating a GraphQL I/O Doc, ensure that the selected API definition has at least one endpoint created and configured as a GraphQL endpoint. If no GraphQL endpoints exist for the selected API definition, select a different API definition or create a new one with a resource endpoint, and configure it as a GraphQL endpoint on the Key & Method Detection page.

         • For the GraphQL API definitions, you can create one interactive documentation item per GraphQL endpoint, allowing multiple interactive documentation items per API definition.

         1. In Name, enter the GraphQL interactive documentation name.

         2. In the GraphQL Endpoint, select a GraphQL endpoint for the selected API Definition.

            note

            If your selected API Definition does not have an endpoint created and configured as a GraphQL endpoint, then you will not be able to select any endpoint.

            Every GraphQL endpoint is associated with a schema configured on the Key & Method Detection page. When you select a GraphQL endpoint here, the associated schema is automatically fetched. Any subsequent changes to the schema on the Key & Method Detection page are automatically reflected in the I/O Doc.

3. Click Save and close or Save and continue.

Modifying an I/O Doc

You can modify a specific I/O Doc on the Control Center's Interactive Documentation page.

Procedure

1. Navigate to Design > Interactive Documentation. This opens the Interactive Documentation page.

2. In the Name column, click the I/O Doc name link or the Settings icon next to the row that you want to update the I/O Doc settings. This opens the Edit Interactive Documentation Settings: <your api name> page.

3. Optional: Select the Default Interactive Documentation to enable the toggle switch and set the selected I/O Doc as the default I/O to appear on the Developer Portal I/O Doc page.

4. Click Save.

Next Steps

To assign or restrict developer access to an I/O Doc on the Developer Portal, configure roles on the Interactive Documentation Access Control page.

For GraphQL I/O Docs, complete the following setup for your authentication type before testing the GraphQL API on the Developer Portal:

• Prerequisites for using API Key authenticated GraphQL I/O Doc
• Prerequisites for using OAuth 2.0 authenticated GraphQL I/O Doc
• Prerequisites for using Secure Hash (SHA-256 or MD5) authenticated GraphQL I/O Doc