Assuming you have followed the previous blog post on documenting your API you will have a nice long description full of great information about your API. But you may notice a problem when looking at the API in the IBM API Connect Developer Portal – when the API is rendered in ‘card’ view then the description gets truncated.

This has to happen in order to render the content in a reasonable sized box, and can of course be customised in a custom theme, but there is another handy option – use a summary field as well as description.

OAI3.1 includes a summary field within the ‘info’ object for precisely this purpose, to be a plaintext overview of the API. The description field can have all the markup, formatting, pictures and information but the summary field is a great way of also being able to provide a concise outline of the API.

For those using OAI3.0, OAI2 or AsyncAPI then the same capability can be used by adding an ‘x-ibm-summary’ field to the info object in your API document. The APIC Developer Portal will then honor that and use it on the ‘card’ view.

Here is version 2 of the API from earlier now updated to also include an x-ibm-summary field:

swagger: '2.0'
info:
  title: Home Assistant
  x-ibm-name: home-assistant
  version: 2.0.0
  x-ibm-summary: >-
    This API retrieves some sensor values from the Home Assistant based smart
    home system. It does this and that and lots more.
  description: >-
    This API retrieves some sensor values from the **Home Assistant** based smart
    home system.
    
    more text

    much more text

    and still some more text 

    ![](https://www.home-assistant.io/images/hero_screenshot.png)

    [Here](https://www.home-assistant.io/) a description of the open source Home Assistant project 

x-ibm-configuration:
  cors:
  enabled: true
  gateway: datapower-api-gateway
  type: rest
  phase: realized
  enforced: true
  testable: true
...

That will then be rendered like this:

I hope this helps you get the most out of your API Developer Portal, as always please let us know any feedback or suggestions.

#developerportal