Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Case Study: Integration Automation Create Delightful API Docs


Published on

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?

Published in: Technology
  • Login to see the comments

  • Be the first to like this

Case Study: Integration Automation Create Delightful API Docs

  1. 1. Case study: Integration and automation create delightful API docs
  2. 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. 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. 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. 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. 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. 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. 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. 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. 10. © 2019 IBM Corporation Authoring | Front matter templates 10 ## Versioning content (all) This documentation describes the current version of {{serviceName}}, `{{}}`. 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}}"{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. 11. © 2019 IBM Corporation API reference output | Non-method information 11 Front matter (Markdown)
  12. 12. © 2019 IBM Corporation Authoring | Request example 12
  13. 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. 14. © 2019 IBM Corporation Authoring | Response example 14
  15. 15. © 2019 IBM Corporation API reference output | Responses 15 OpenAPI path > responses> 200 > examples
  16. 16. © 2019 IBM Corporation Authoring | Request example 16
  17. 17. © 2019 IBM Corporation API reference output | Content per programming language 17
  18. 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. 19. © 2019 IBM Corporation Demo | Then, the magic happens… 19
  20. 20. © 2019 IBM Corporation Resources | Docs and projects • IBM Cloud API docs: • OpenAPI validator: • API guidelines: • Watson SDKs: • Guidelines for SDK compatibility: compatibility 20