Case Study: Integration Automation Create Delightful API Docs
0 likes149 views
The document presents a case study by IBM on the integration and automation of API documentation using OpenAPI 2.0 and 3.0 to enhance documentation quality and developer experience. It outlines the strategies and tools used for creating, validating, and delivering API documentation, emphasizing the importance of metrics, automated testing, and collaborative authoring. Significant improvements in content quality and user engagement following their initiatives are highlighted.
Case Study: Integration Automation Create Delightful API Docs
- 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