Search results

Implementing Swagger in your API documentation -- My ISTC article

by Tom Johnson on Sep 8, 2016
categories: technical-writing api-doc

I recently published an article about Swagger in the Autumn 2016 edition of ISTC's magazine, Communicator. ISTC stands for Institute of Scientific and Technical Communicators. My article provides an introduction to using Swagger (now called OpenAPI specification) for publishing your REST API documentation.

If you’re an ISTC member, then you already get the ISTC Communicator, and you can read my article in print or by logging into the ISTC site. You can view the table of contents for the Autumn 2016 here (but not the article content unless you log in as a member).

If you’re not an ISTC member, you can read my article here: Implementing Swagger (OpenAPI specification) with your REST API documentation (PDF). I originally published this content on my API doc course, but the course content has since evolved and now the original article in that context is no longer there. See OpenAPI spec and generated reference docs for the latest approach.

A lot of people ask about Swagger, and although I’ve written about Swagger previously, this is my clearest and most thorough article on the topic to date.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.