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
[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: