STC San Diego

  • Home
  • Events
    • Events Calendar
    • Meeting Archive
  • News/Blog
  • Professional Development
    • Webinars
    • Education
    • Conferences
    • STC Publications
    • Organizations and User Groups
  • Job Resources
    • Job Listings
    • Job Listings on LinkedIn
    • Recommended Job Boards
    • Job Hunting Tips
    • Agencies
    • Career Evaluation Tests
    • Salary Survey
  • About
    • What is Technical Communication?
    • Become a Volunteer
    • Council Members and Volunteers
    • Become a Corporate Sponsor
    • Our Corporate Sponsors
  • Membership
    • STC’s Mission and Vision
  • Subscribe
  • Contact

02/13/2018 By Alice Brzovic

February Meeting: Swagger UI and the Open API Specification with Tom Johnson

Date/Time
Date(s) - 02/13/2018
7:00 pm - 8:30 pm


Register Now on Eventbrite!

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.

Register Now on Eventbrite!

About the Presenter

tom johnson from idratherbewritingTom 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.

Don’t forget to register so you can get access to the virtual presentation: http://bit.ly/2E0Yvez

Map Unavailable

Share this:

  • Click to email this to a friend (Opens in new window)
  • Click to print (Opens in new window)
  • Click to share on LinkedIn (Opens in new window)
  • Click to share on Facebook (Opens in new window)
  • Click to share on Google+ (Opens in new window)
  • Click to share on Pinterest (Opens in new window)
  • Click to share on Pocket (Opens in new window)
  • Click to share on Reddit (Opens in new window)
  • Click to share on Twitter (Opens in new window)
  • Click to share on Tumblr (Opens in new window)

Search This Site

Upcoming Events

  • UX Writing Panel Discussion
    05/08/2018

Join the Mailing List

You don't have to be a member of STC to stay informed with STC San Diego happenings. Just sign up for our free newsletter.

Support STC San Diego

Amazon donates to STC San Diego when you shop at smile.amazon.com.

Recent Posts

  • Editing for Mobile with Shelly Bowen – Key Takeaways 04/11/2018
  • STC San Diego recognized as a Platinum Community 03/26/2018
  • Get more from your STC membership with an upgrade. 03/17/2018
  • Coming Soon – STC’s New Conference App 03/17/2018
  • STC Summit Anniversary Rate Extended to Feb. 5th! 02/01/2018
  • Member discount ends 1/31. Register now for STC Summit 2018! 01/27/2018
  • Add video production to your technical communication skills! Join us on Nov. 14th. 11/09/2017

Archives

STC San Diego Twitter Feed

My Tweets

Gold Sponsors

MadCap Software
Adobe Technical Communication

Silver Sponsors

Acrolinx

Upcoming Events

  • UX Writing Panel Discussion
    • 05/08/2018
    • San Diego

Recent Posts

  • Editing for Mobile with Shelly Bowen – Key Takeaways 04/11/2018
  • STC San Diego recognized as a Platinum Community 03/26/2018
  • Get more from your STC membership with an upgrade. 03/17/2018
  • Coming Soon – STC’s New Conference App 03/17/2018
  • STC Summit Anniversary Rate Extended to Feb. 5th! 02/01/2018

Support STC-San Diego

STC-San Diego is a 501(c)3 charitable organization. Help support us by donating through PayPal.

Donate Every Time You Shop

Let’s Be Social

  • Facebook
  • Linkedin
  • Twitter
  • YouTube
  • Home
  • Events
  • News/Blog
  • Professional Development
  • Job Resources
  • About
  • Membership
  • Subscribe
  • Contact

Copyright © 2018 · STC San Diego

loading Cancel
Post was not sent - check your email addresses!
Email check failed, please try again
Sorry, your blog cannot share posts by email.