There’s more to your API docs than Curl. Sync your non-reference content. Include request examples. Generate SDK docs from the OpenAPI definition. Want to know how we did it?

1. Case study:
Integration and
automation create
delightful API docs

2. © 2019 IBM Corporation
API the Docs | Case Study: Integration and automation create delightful API docs
Agenda
Today, we’ll show how we generate from OpenAPI 2 or 3, Markdown,
and an SDK generator project.
We'll show our authoring environment and fast, automated build.
Finally, some bits about how we promote quality from up front
guidance to post-build dashboards.
2

3. © 2019 IBM Corporation
Who we are | IBM Cloud
Allen Dean
Senior Content Strategist, IBM
Watson Developer Experience
Jenifer Schlotfeldt
Content Experience Architect,
IBM Cloud
3

4. © 2019 IBM Corporation
Scope and strategy | Volume, scale, goals
Volume and scale
• IBM Cloud has over 190 services, and customers look for one place to find all the API Docs
available
Support developers and writers
• Swagger 2.0 and now OpenAPI 3.0
• Creating non-method front matter and editing descriptions and examples
• Collaborative authoring with SMEs
Improve speed, quality, and compliance
• Decrease time from feature release to documentation and SDK support
• Avoid “copy-and-paste” and other errors from hand-written SDKs and API docs
• Improve and enforce the agreement among the API definition, the API docs, and the SDKs
4

5. © 2019 IBM Corporation
Metrics and Quality | Analytics and Dashboard
• Automated test cases reported on our Content Quality Dashboard
• since our latest initiative, we’ve seen over 1000% increase in usage
5

6. © 2019 IBM Corporation
DevOps | Develop. Validate. Build. Deliver.
OpenAPI Definition
Commit
Definition
SDK Tests
Publish via
Continuous
Delivery
Developer
Language SDKs
Validate
Definition
Generate
SDK
Generate
SDK Reference
Automated
Testing
Continuous IntegrationDevelopment Continuous Delivery
Jenkins

7. © 2019 IBM Corporation
ContentOps | Author. Build. Validate. Deliver.
OpenAPI Definition
Commit in GH
Enterprise
Publish via
Continuous
Delivery
Writer
Validate
Definition
Generate
API Doc
Validate
Markdown Automated
Testing
Continuous IntegrationAuthor Continuous Delivery
Jenkins
Front Matter
API Docs
SDK
Reference

8. © 2019 IBM Corporation
Authoring | Components
Markdown
• The front matter (non-method) content
• Manually create markdown with attributes (or generate from templates)
OpenAPI definition + extensions
• Generate request example syntax
• Enable or hide features and methods
JSON "blob" (from SDK generator)
• The SDK method info
• All the "middle pane" content for the SDKs
8

9. © 2019 IBM Corporation
Authoring | IBM Cloud common extensions
9
Property Type Description
x-sdk-exclude boolean
Exclude a method or property from the
SDKs
x-sdk-operations object
Language-specific request examples and
info
x-try-it-out-enabled boolean Display the "Try-it-out" feature
x-version-date string
Minor version constants for the SDK and
front matter content
x-watson-host string
Host value for the API if it doesn't follow
the standard

10. © 2019 IBM Corporation
Authoring | Front matter templates
10
## Versioning content (all)
This documentation describes the current version of {{serviceName}}, `{{swagger.info.x-version-date}}`.
In some cases, differences in earlier versions are noted in the descriptions of parameters and response
models.
{: tip}
## Authentication example (java)
{: java}
{: right}
```java
IamOptions options = new IamOptions.Builder()
.apiKey("{apikey}")
.build();
{{upperCamelCase sdkName}} {{camelCase sdkName}} = new {{upperCamelCase sdkName}}
({{#if swagger.info.x-version-date}}"{version}", {{/if}}options);
```
Specifies the language
and location to print in the UI
From config file From OpenAPI extension
From OpenAPI extension
From config file

11. © 2019 IBM Corporation
API reference output | Non-method information
11
Front matter (Markdown)

12. © 2019 IBM Corporation
Authoring | Request example
12

13. © 2019 IBM Corporation
API reference output | Organization, definition details, and examples
13
OpenAPI tag
OpenAPI description
OpenAPI summary
OpenAPI x-sdk-operation >
request examples > (lang)
OpenAPI enum
OpenAPI default
OpenAPI parameters

14. © 2019 IBM Corporation
Authoring | Response example
14

15. © 2019 IBM Corporation
API reference output | Responses
15
OpenAPI path > responses>
200 > examples

16. © 2019 IBM Corporation
Authoring | Request example
16

17. © 2019 IBM Corporation
API reference output | Content per programming language
17

18. © 2019 IBM Corporation
API reference output | Expanded parameter examples
18
A JSON string in a request
body -- provides detail that we
can't put easily into the right
hand pane
A response example detail that
has more than we can put in
the right hand pane

19. © 2019 IBM Corporation
Demo | Then, the magic happens…
19

20. © 2019 IBM Corporation
Resources | Docs and projects
• IBM Cloud API docs: https://cloud.ibm.com/apidocs
• OpenAPI validator: https://github.com/IBM/openapi-validator
• API guidelines: https://github.com/watson-developer-cloud/api-guidelines
• Watson SDKs: https://github.com/watson-developer-cloud/
• Guidelines for SDK compatibility: http://watson-developer-cloud.github.io/api-guidelines/sdk-
compatibility
20