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

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.

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.

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 ?

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.