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.

You can embed additional documentation pages within the api swagger documentation. These pages can be base64 encoded strings or markdown strings of the html content of the page. These pages show up in the navigation, on the left side, underneath the overview for that product or API, and above the paths. Any styling that is needed to theme the documentation can be included in the Developer Portal custom theme.

Embedded docs for products and APIs

You can embed documentation for individual products and APIs by specifying an additional x-embedded-doc object in the product or API specification.

Field name Type Description
name string Required, the name of the embedded document
title string Required, The display title of the embedded document
format string Optional, the format of the embedded document content value. Values are b64html or md. Default value is md.
content string The base64 encoded html of page, or, the markdown string.
docs x-embedded-doc Additional embedded documentation. If no content is specified for parent, then the first child is the content that is shown.

Hierarchies of documents are supported by nesting of further doc properties. Language support is available by using x-ibm-languages.

Examples

Documentation can be added to an api, by using the following JSON:
 "x-embedded-doc": [
    {
      "name": "introduction",
      "title": "Introduction",
      "format": "md",
      "content": "# some markdown"
    },
    {
      "name": "concepts",
      "title": "Concepts",
      "format": "md",
      "content": "## more markdown"
    },
    {
    	"name": "authentication",
    	"title": "Authentication",
    	"docs": [{
              "name": "auth_clientid_secret",
              "title": "Obtaining a Client ID and Secret",
              "format": "md",
              "content": "### even more markdown"
              },
              {
                "name": "auth_bearertoken",
                "title": "Getting and Using a Bearer Token",
                "format": "md",
                "content": "#### yet more markdown"
              }
              ]
    }
  ]
Alternatively, by using base 64 encoded HTML: 
"x-embedded-doc": [
  {
    "name": "introduction",
    "title": "Introduction",
    "format": "b64html",
    "content": "PGFydGljbGUgaWQ9ImludHJvZHVjdGlvbiIgY2xhc3M...."
  },
  {
    "name": "concepts",
    "title": "Concepts",
    "format": "b64html",
    "content": "PGFydGljbGUgaWQ9ImNvbmNlcHRzIiBjbGFzcz0icGFnZSI....."
  },
  {
    "name": "authentication",
    "title": "Authentication",
    "docs": [{
            "name": "auth_clientid_secret",
            "title": "Obtaining a Client ID and Secret",
            "format": "b64html",
            "content": "PGFydGljbGUgaWQ9ImNsaWVudC1pZC1zZWNyZX....."
            },
            {
            "name": "auth_bearertoken",
            "title": "Getting and Using a Bearer Token",
            "format": "b64html",
            "content": "ICA8YXJ0aWNsZSBpZD0iYmVhcmVyLXRva2VuIiBjbGFz....."
            }
          ]
      }
]
Or mixed formats: 
"x-embedded-doc": [
  {
    "name": "introduction",
    "title": "Introduction",
    "format": "b64html",
    "content": "PGFydGljbGUgaWQ9ImludHJvZHVjdGlvbiIgY2xhc3M...."
  },
  {
    "name": "concepts",
    "title": "Concepts",
    "format": "md",
    "content": "# some markdown"
  }
]
An example of some x-embedded-doc code and how it might render: 
x-embedded-doc:
  - name: document
    title: Interesting
    format: b64html
    content: >-
      PGFydGljbGUgaWQ9ImNsaWVudC1pZ...=
securityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: api_key
Screenshot including new entry in side bar
An example of some x-embedded-doc code into a product and how it might render: 
x-embedded-doc:
  - name: introduction
    title: Introduction
    format: md
    content: >-
      ## Overview  

      ### Philosophy 

      Markdown is intended to be as easy-to-read and easy-to-write as is
      feasible. Compellingly facilitate 2.0 intellectual capital for
      cross-platform networks.  Dynamically incubate ethical sources after
      optimal technologies. Phosfluorescently restore global users via excellent
      niche markets. Credibly impact cross-media mindshare through strategic
      best practices. Synergistically impact interdependent web services rather
      than unique interfaces.

      Continually reintermediate enabled sources rather than professional
      architectures. Appropriately embrace viral collaboration and idea-sharing
      whereas granular solutions. Energistically revolutionize competitive
      paradigms vis-a-vis highly efficient models. Objectively incentivize
      enterprise customer service through compelling e-markets. Competently grow
      multifunctional e-markets with business methods of empowerment.

      Dramatically iterate equity invested scenarios and focused data.
      Compellingly reconceptualize next-generation deliverables rather than
      out-of-the-box architectures. Competently foster cross-unit web services
      with interactive innovation. Quickly revolutionize enabled communities and
      alternative content. Globally administrate resource maximizing
      deliverables whereas corporate e-business.

      Progressively develop maintainable leadership.
  - name: concepts
    title: Concepts
    format: md
    content: '## some more markdown'
  - name: moreinfo
    title: Even more info
    docs:
      - name: moreinfo1
        title: More Info 1
        format: md
        content: '### even more markdown'
      - name: moreinfo2
        title: More Info 2
        format: md
        content: '#### yet more markdown'
Screenshot including words in the overviewr