I'd Rather Be Writing Podcast

I'd Rather Be Writing Podcast


Recording of OpenAPI and Swagger presentation (for STC and WTD San Diego)

February 14, 2018

Video You can watch two versions of the video. If you want the STC San Diego version that includes my talking head and the STC / WTD intro remarks, see this video: I didn’t like how my talking head seemed to squish the video over to the left, so I also uploaded my own recording. This second recording excludes the talking head and expands the window full screen, and also shows the chat window and occasional webinar controls. Slides Here are the slides: Audio only Listen to this post: You can download the MP3 file, subscribe in iTunes, or listen with Stitcher. Presentation description Swagger UI and the OpenAPI specification OpenAPI is a specification for describing REST APIs. As an analogy, you can think of the OpenAPI specification like the specification for DITA. With DITA, there are specific XML elements used to define help components, and a required order and hierarchy to those elements. Different tools can read DITA and build out a documentation website from the information. With OpenAPI, instead of XML, you have set of JSON objects, with a specific schema that defines their naming, order, and contents. This JSON file describes each part of your REST API (the endpoints, parameters, responses, etc). By describing your API in a standard format, publishing tools can programmatically ingest the information and process it. Swagger UI provides one option to read the OpenAPI specification document and generate an interactive documentation website from it. Interactive documentation created with Swagger lets users try out requests and see actual responses directly from within the documentation. You can read the details in either the STC or WTD event pages: STC San Diego Write the Docs - San Diego The event was held February 13, 2018. var contents=new Array() contents[0]=' Sponsored message:Over 40,000 API developers use SwaggerHub to design and document APIs with Swagger (OpenAPI). Learn how SwaggerHub can help improve your team’s API documentation workflow. Get started for free.' contents[1]=' Sponsored message:SwaggerHub was built by the team behind Swagger to help organizations collaborate on their API design and documentation from one centralized platform. Find out why SwaggerHub is the platform for design and documenting APIs with Swagger. Get started for free.' contents[2]=' Sponsored message:SwaggerHub brings together all the power of the open source Swagger tooling into one integrated platform for designing and documenting APIs with Swagger (OpenAPI). Get started for free.' contents[3]=' Sponsored message:SwaggerHub is an integrated API design and documentation platform, built for teams to drive consistency and discipline across the API development workflow. Get started for free.' contents[4]=' Sponsored message:Documenting APIs with Swagger? SwaggerHub lets you generate API documentation that’s securely hosted and fully interactive. Import an existing Swagger definition, or start a new API project from right within your browser, no setup required. Get started for free.' var i=0 //variable used to contain controlled random number var random //while all of array elements haven't been cycled thru while (i