Verwendung von x-embedded-doc zum Hinzufügen zusätzlicher Dokumentation zu Produkten und APIs
Sie können x-embedded-doc verwenden, um zusätzliche Dokumentation zu einem Produkt oder einer API als Teil ihrer Definition hinzuzufügen.
Sie können zusätzliche Dokumentationsseiten in die API-Swagger-Dokumentation integrieren. Bei diesen Seiten kann es sich um base64-codierte Zeichenfolgen oder um Markdown-Zeichenfolgen des HTML-Inhalts der Seite handeln. Diese Seiten werden in der Navigation auf der linken Seite unter der Übersicht für das jeweilige Produkt oder die jeweilige API und über den Pfaden angezeigt. Alle Stile, die für das Motiv der Dokumentation erforderlich sind, können in das angepasste Motiv Developer Portal eingeschlossen werden.
Integrierte Dokumente für Produkte und APIs
Sie können die Dokumentation für einzelne Produkte und APIs integrieren, indem Sie ein zusätzliches x-embedded-doc-Objekt in der Produkt- oder API-Spezifikation angeben.
| Feldname | Typ | Beschreibung |
|---|---|---|
| Name | string |
Erforderlich, der Name des eingebetteten Dokuments |
| Titel | string |
Erforderlich, der Anzeigentitel des eingebetteten Dokuments |
| Format | string |
Optional: Das Format des eingebetteten Dokumentinhaltswerts. Gültige Werte sind b64html oder md. Der Standardwert istmd. |
| inhalt | string |
Die base64-codierte HTML der Seite oder die Markdown-Zeichenfolge. |
| Dokumente | x-embedded-doc |
Zusätzliche eingebettete Dokumentation. Wenn kein Inhalt für das übergeordnete Element angegeben wird, ist das erste untergeordnete Element der Inhalt, der angezeigt wird. |
Hierarchien von Dokumenten werden durch Verschachtelung von weiteren Dokumenteigenschaften unterstützt. Sprachunterstützung ist mit x-ibm-languages verfügbar.
Beispiele
Dokumentation kann mithilfe der folgenden JSON zu einer API hinzugefügt werden:
"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"
}
]
}
]Alternativ mithilfe einer base64-codierten 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....."
}
]
}
]Oder gemischte Formate:
"x-embedded-doc": [
{
"name": "introduction",
"title": "Introduction",
"format": "b64html",
"content": "PGFydGljbGUgaWQ9ImludHJvZHVjdGlvbiIgY2xhc3M...."
},
{
"name": "concepts",
"title": "Concepts",
"format": "md",
"content": "# some markdown"
}
]Ein Beispiel für 
x-embedded-doc-Code und dafür, wie dieser ausgegeben werden könnte:x-embedded-doc:
- name: document
title: Interesting
format: b64html
content: >-
PGFydGljbGUgaWQ9ImNsaWVudC1pZ...=
securityDefinitions:
api_key:
type: apiKey
in: header
name: api_keyEin Beispiel für 
x-embedded-doc-Code in einem Produkt und dafür, wie dieser ausgegeben werden könnte: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'