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

17 views

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
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • 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}}, `{{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. 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: 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

×