Question 19789 in Amazon Web Sevices Question posted in
The official Amazon Web Services documentation can be found here.

How to add comprehensive introduction to AWS Api Developer portal?

We have created new Rest API To AWS Api Gateway by importing our existing Swagger file. File contains quite long and good introduction for developers about our API. It is Markdown markup language.
AWS Api gateway is able to show whole documentation correctly in documentations section.
Our API is published to Developer portal. Developer portal shows only the first line of the description part of the documentation. Our Markdown documentation contains linefeeds,subtitles,lists few images and so on. Methods and other documentation parts are ok in Developer portal.
I can edit and publish that API part of the documentation to the Developer portal. But only the first line. Is it possible to show better introduction about API in Developer portal than just one line description?

I have asked that same question from AWS support including original JSON file. I haven’t got an answer so I hope someone else knows how to publish longer API introduction to Developer portal.
if this isn’t possible is there way to include link to other documentation outside Developer portal?

In AWS documentation there is JSON example about documentation. When this is copy/pasted to Api Gateway (Documentation -> API part) and published to Developer portal only one description line is showing.
https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-documenting-api-quick-start-with-console.html

{
"info": {
"description": "Your first API Gateway API.",
"contact": {
"name": "John Doe",
"email": "[email protected]"
}
}
}

Tags:

2

Answers


  1. Chosen as BEST ANSWER
    0

    I got answer from AWS support. They were able to reproduce problem. Developer portal doesn't show all Markdown written in Api Gateway documentations API part. Only the first line. As a workaround I wrote one sentence Api description including url to better external documentation page. Html link didn't work.


  2. 0

    To provide a link to external documentation you can use this in a documentation API part.

    {
  "externalDocs": {
    "description": "See documentation here",
    "url": "https://foo.bar.com/ApiDocumentation"
  }
}
    Login or Signup to reply.
Please signup or login to give your own answer.

Back To Top
Search