Using the API Assistant to document your APIs

You can use the specification enhancements component of the API Assistant to help you improve your API documentation by analyzing your API definition, and generating recommendations for your descriptions and examples. Enhancing your API specification accelerates its adoption by consumers.

The specification enhancement component uses the IBM watsonx Granite LLM models to help you build your APIs faster. Take advantage of the API Assistant to quickly generate clear and concise descriptions and examples for documenting your API definitions.

How to use the API Assistant to generate examples and descriptions for your API

You use the API Assistant while creating or editing an API definition in the API Manager UI. The API Assistant reviews the API definition, and suggests descriptions and examples for fields in the schema. You can then choose which suggestions you want API Connect to incorporate into your API definition.

  1. Log in to API Connect Enterprise as a Service using a Premium subscription.
  2. In API Manager, open an OpenAPI 3.0 API that you'd like to edit.
  3. In the Design tab, click the source view icon (which is a small grey square containing two angle brackets that enclose a forward slash) to work in the Source view.
  4. Click the AI icon (which is a small grey, square containing the letters AI and an arrow in black) to open the API Assistant panel.
  5. Ensure that the Specification enchancements panel is open, and click Generate to request AI suggestions for the API description and examples.
  6. Click Apply for each suggestion that you want to incorporate into your API.

    To quickly accept all suggestions, click Apply all.

  7. Click Save to save the updated API definition.

Example: Enhancing the EmployeesApi sample API

In this example we're using an EmployeesApi to show the flow through generating some AI suggestions, reviewing the suggestions, and then applying them to the API. You can follow the steps through with your own API.

  1. Log in to API Connect Enterprise as a Service using a Premium subscription.

  2. In API Manager, click the Develop icon (which is a small black square containing an outline of a white pencil) Develop to open the API development page, and then ensure that the APIs tab is selected so you can view your APIs.
    Open the Develop page

  3. Select an API of Type OpenAPI 3.0 (REST), and click its Title to edit it.
    Edit an OpenAPI 3.0 API

  4. The Design page opens in Form view.

    Notice that the sample API is missing descriptions for some properties.

    The sample API is missing property descriptions

  5. Click the source view icon (which is a small grey square containing two angle brackets that enclose a forward slash) to work in the Source view.

    API Assistant is easier to use when you can see the source code for your API.

    Use the Source view to see the API code
  6. Click the AI icon (which is a small grey, square containing the letters AI and an arrow in black) to open the API Assistant panel. Ensure that the Specification enhancements tab is selected.
  7. In the Specification enhancements panel, you can click the AI explained icon (which is the outline of a small black square, containing the letters AI) to learn more about how the API Assistant uses AI to improve your API definitions.
    Learn more about the API Assistant

    Click the AI explained icon (which is the outline of a small black square, containing the letters AI) again to close the pop-up.

  8. Now click Generate to see if some AI suggestions are recommended for your API.

    In our sample API, the API Assistant analyzes the API definition and returns suggested text for all of the empty descriptions and examples.

    Click Generate and view the suggestions

    Notice the following changes to the display:

    • The API Assistant panel displays the name of each field and the suggested description or example. The corresponding values are also inserted and highlighted in the API source code so you can see them in place.

      While the API Assistant panel is open, the API source code is in read-only mode to prevent accidental updates. When you close the panel, the code becomes editable again.

    • If a property already contains a description or an example, the existing value is preserved. For example, in our sample API, the employeeNumber property already contains a description of test so a suggestion is not generated for it.
    • In the Design menu, the AI suggestion provided and Delete icon icons display for any section of the API definition that received suggestions, so you can easily jump to, or delete, that suggestion.
  9. When you are ready to accept or decline the suggestions, take one of the following actions:
    • Accept all suggestions:

      Click Apply all to quickly accept all suggestions.

    • Regenerate all suggestions:

      Click the Regenerate all icon to regenerate all suggestions that were not already applied.

    • Accept a suggestion:

      Click Apply for each suggestion that you want to accept.

    • Delete a suggestion:

      Click Delete icon for each suggestion that you want to delete.

    As you work with the suggestions, note the following behavior:

    • Any suggestions that you apply are added to the API definition, but the definition itself is not saved until you click Save in the page header.
    • When you click Save, your own changes and all applied suggestions are saved; however, any suggestions that you did not apply are lost.
    • If you navigate away from the API Design page before applying a suggestion, that suggestion is lost.
    • At any time, you can edit the API again and generate suggestions for any empty descriptions and examples.
  10. Click Close icon to close the API Assistant panel.

  11. Return to the Form view by clicking the form view icon (which is a small grey square containing the outline in black of a piece of paper with a pencil).

    In the sample API, you can see that the Description fields for the EmployeeBody properties now contain the suggested descriptions.

    Applied suggestions are added to the API definition

  12. Remember to click Save to save the updated API definition.