There are a number of ways to attach and associate documentation to an API in the portal. One of my colleagues authored this blog post which gives a summary, with links to the official documentation, on the varied ways on doing so.
"How to document an API" - Chris Dudley
It is worth bearing in mind that docs are separate to API definitions, publishing significant attachments to the gateway would come with a performance hit.
------------------------------
Anne Redwood
------------------------------
Original Message:
Sent: Fri May 10, 2024 09:21 PM
From: Syed Imtiyaz Alam
Subject: x-embedded-doc in YAML file
Thank you Anne, could you please elaborate where can I attach the doc and where it can be downloaded ? Can this become part of YAML itself when we download the YAML ?
------------------------------
Syed Imtiyaz Alam
Original Message:
Sent: Fri May 10, 2024 11:40 AM
From: Anne Redwood
Subject: x-embedded-doc in YAML file
This is working as designed - if you want to make this kind of content available to the consumer then you could attach a doc, pdf or zip to the API in the portal which would be downloadable which would provide more legible documentation than that embedded in an api yaml or json spec.
------------------------------
Anne Redwood
Original Message:
Sent: Wed May 08, 2024 05:32 PM
From: Syed Imtiyaz Alam
Subject: x-embedded-doc in YAML file
Hi,
I am trying to use this parameter "x-embedded-doc" from the Using x-embedded-doc to add additional documentation to products and APIs
| Ibm | remove preview |
| | Using x-embedded-doc to add additional documentation to products and APIs | | You can use x-embedded-doc to add additional documentation to a product or an API as part of their definition. | | View this on Ibm > |
|
|
and it works but the issue is when we download the API yaml file from the developer portal, this section is missing from the downloaded YAML file.
So my question is this expected ? or do we have any way to fix this.
------------------------------
Syed Imtiyaz Alam
------------------------------