Adobe Trends webinar

Get new posts delivered straight to your inbox.

Subscriber count: 4,300

Stitcher radio

Search results

Adobe Trends webinar

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

Feb 14, 2018 • api-doc, podcasts, stitcher

I recently gave a presentation to the STC San Diego chapter and WTD San Diego group called "Swagger UI and the OpenAPI specification" (February 13, 2018). You can view a recording of the presentation, browse the slides, and listen to the audio here.

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

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:

The event was held February 13, 2018.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 4,300

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in , API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.