API Strategy & Practice Conference 2018

The Watson Cloud team at IBM have built a system to generate SDKs and API Reference documentation from OpenAPI descriptions of the IBM Watson Cloud services. They developed a methodology that includes standards for API design and description, based on OpenAPI but with extensions to capture special API or SDK features, along with a validator that ensures compliance to these standards. They built tools using the Swagger Codegen framework that generate product-quality SDKs that incorporate best practices for API design, code structure, documentation, and extensibility in each target language, and API reference documentation focused around these SDKs. Their methodology and tools enable them to achieve this result for less internal effort than would be possible with existing tools. This talk will describe their system in hopes that it will help others generate usable SDKs and documentation.