Swagger API: How They Work & What you Need to Know

What is Swagger?

Let’s begin by getting some terminology correct. Because the OpenAPI specification was originally called SwaggerAPI, sometimes people still refer to the OpenAPI specification as Swagger. Throughout this article, when we say Swagger we’ll be referring to a suite of tools produced to help design, build and document APIs using the OpenAPI specification.

Swagger tools for API documentation

As well as “pro” tools (subscription-based), Swagger offers a popular suite of open-source tools for API development and documentation, including:

Swagger Editor

Swagger Editor is primarily a tool for developers to design and build their RESTful APIs while validating against the OpenAPI specification as you go. Swagger Editor also visualizes the API, allowing the team to document the API from the beginning. The advantage of the API design first approach is that it will enable you to design the API and use it to create the OpenAPI specification, and you can create mock servers to mimic API responses.

Swagger Codegen

Swagger Codegen allows you to create server stubs (code to simulate server responses to API calls) and SDKs (Software Development Kits – a set of tools to help developers to integrate your API into their system). Technical Writers are sometimes involved in SDKs if they have suitable technical knowledge and experience.

Swagger UI

Swagger UI is the tool in which the Technical Writer is most likely to get involved with the creation of Swagger API documentation. Swagger UI provides a visual representation of the API and its documentation. It takes the YAML or JSON file and displays it as interactive documentation, allowing users to try out the API calls in the browser; Showing the available end-points and allowing calls to each end-point.

Swagger Hub

A swagger hub is the latest offering from the Swagger team which provides a hosted environment combining Swagger Editor, Swagger Codegen, and Swagger UI in one interface.

Read More: Top 6 SwaggerHub Alternatives in 2023

What can you do with Swagger?

Those are the tools that Swagger provides, but using Swagger, as well as creating documentation along with your APIs, you can also document existing APIs, integrate with any development environment, and make sure that you’re compliant with the latest OpenAPI specification.

Also, check out our article on FinTech API.

Who can benefit from Swagger?

• OpenAPI definitions are plain text documents that can be held in any kind of repository, like GitHub for example, which means that they can be worked on in a collaborative environment.
• If speed and reliability are important to your project, creating your API in Swagger Editor means that your developers will have access to autocomplete options and live error reports to remain compliant with the specification; and using codegen allows you to leverage Swagger’s automated code for SDKs.
• You don’t have an API or API documentation available, but your customers/partners are demanding one. You can use Swagger Editor to design an API and expose endpoints using a mock server, before implementing it in your product.
• An API is only as good as its documentation, after all, we can’t use APIs if there are non-existent, incomplete, or difficult-to-use explanations of how the API works. Swagger UI allows you to easily produce documentation from the code.

How to create API documentation using Swagger

First of all, if you’re not familiar with Swagger already, I strongly recommend that you start with Swagger’s own Petstore demo here: https://petstore.swagger.io/. You can see how a Swagger documentation site will look, you can open the JSON file that it is built from. You can see the end-points and their available calls, and try out GET, PUT, POST and DELETE calls where appropriate.

Top-down or bottom-up?

Using a top-down approach means starting with Swagger Editor and creating/editing the API documentation along with the API. Whilst this may be the preferred option for most Technical Writers, it is generally seen by development teams as a technique that slows the production of the API itself.

The top-down development approach allows new start-ups or new projects to design the API and use it to generate the OpenAPI specification, which means that they can supply automated documentation and mock servers to mimic the API responses.

The bottom-up approach (also known as the code-first approach) is much more common and usually involves the Technical Writer taking a completed API and using Swagger UI to create online, interactive documentation. This way, the API development isn’t kept waiting whilst the documentation is finished.

Editing and reviewing Swagger files

Using Swagger Editor allows you to either load your YAML or JSON definition file or create a new one from scratch. You can see the demo of Swagger Editor using the Petstore specification here: https://editor.swagger.io/. Using the Swagger editor means that any structural, or typing errors are brought to your attention immediately and you can see how they will appear in the documentation, which means that any changes needed can be made to the file on the fly.

Creating client libraries in Swagger

A client library provides chunks of code in a particular language that developers can add to their projects to interact with your API. Using client libraries speeds up development as the developers don’t have to write everything from scratch. Using the free tool, Swagger Codegen, you can create client libraries directly from your Swagger API, for most languages including, Android, C#, C++, Java, Javascript, Go, ObjC, PHP, Python, Ruby, Scala, and many more. Codegen uses a template-driven engine to analyze/parse your OpenAPI definitions and produce client SDKs for your chosen languages.

Integrating Swagger documentation with other tools

As a Technical Writer, you’ll probably have a preferred writing tool, or maybe you’ve inherited one in your current role; In any case, to preserve the “single source of truth” and to prevent repetition, you’ll want to integrate your API documentation with your other documentation at some point. The simplest way is to use the “External Documentation” object within the API documentation to refer out to other documentation.

Alternatively, if you already have a documentation site, the API documentation can be embedded within a page (although this always ends up looking a bit clunky). Finally, you can use a tool that will import your Swagger documentation and allow you to add more content. Tools like Readme.com, Stoplight, Apiary, and Mulesoft, for example, allow you to import your Swagger documents and add more content. Whilst you may also want to make your traditional technical documentation tools such as Flare, and RoboHelp incorporate your API documentation, it can be done but is quite a lengthy process.

Swagger API documentation best practices

Best practices for API documentation with Swagger are largely the same as for any documentation project, but the end audience may be a little different. For example, whilst we’re not writing for machines, we are writing for a highly technical audience so whilst the content must be readable, getting to the point is very important.Include code samples and examples of how to use the APIs.

Make sure that you use consistent terminology and tone of voice throughout, this isn’t a novel so you don’t need to keep thinking of new ways to express yourself. If you must use technical terminology, acronyms, and/or abbreviations, make sure that they’re industry standard and widely understood, and explain them in a glossary if appropriate. Finally, make sure that your documentation is kept up to date; out-of-date documentation can be misleading, time-consuming, and potentially damaging to end users.

Also Read: What is Open API ? Advantages, Disadvantages & Examples

Swagger API documentation Examples

Here are some public Swagger API documentation examples:

ETER (European Tertiary Education Register) API

ETER (European Tertiary Education Register) have used Swagger to document API access to their database here: https://www.eter-project.com/api/doc/. You can see that they refer out to the rest of their documentation and all their endpoints and methods are listed, along with the capacity to try them out.

Nokia Motive Connected Device Platform API 

Nokia Motive Connected Device Platform API Swagger documentation, whilst not showing any high-level information or links out to other documentation, it does show how the interface appearance can be modified with CSS to reflect your own color scheme, fonts, etc.

Connect Public API

The Connect Public API documentation from the Objective Corporation shows a good level of introductory information, and plenty of explanatory text for endpoints, methods, and schemas.

Also check out our guide to launch public API

Apache OpenMeetings API

Apache OpenMeetings API documentation provides one of the most comprehensive introductory text sections, including information on what it is for, how to use it, links to examples, links to related modules, and links to the website and to contact the team.