Date/Time
Date(s) - 02/13/2018
7:00 pm - 8:30 pm
This event has passed – come to next one!
This event is a virtual presentation co-hosted by STC-San Diego and WTD-San Diego.
Documenting APIs is an increasingly common requirement in technical communication, and we dig in to the topic in February with a virtual presentation by Tom Johnson, author of the popular technical writing blog Idratherbewriting.com. Tom’s presentation will cover basic concepts behind API documentation, and introduce the OpenAPI specification and API documentation tool Swagger UI.
If you don’t already work with APIs, a visit to the Documenting APIs guide at Idratherbewriting.com is recommended before February’s presentation. The recorded presentation Introduction to API Documentation is a great resource there.
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.
About the Presenter
Tom Johnson is a technical writer for Amazon in Sunnyvale, California. He writes a popular blog on technical writing called Idratherbewriting.com, where he explores topics such as API documentation, trends, information design, and more. He also has an extensive online course on API documentation that includes extensive tutorials and other exercises you can follow to build your expertise with APIs, including the OpenAPI specification, Swagger, and more.
