Category: API Documentation
Last updated on Jan 23, 2023
You or your development team have decided on a RESTful API, to take full advantage of the REST framework’s flexibility, speed and efficiency. However, where SOAP is a protocol designed with a specification, REST is an architecture and so requires a specification to define how data is handled and processed. The OpenAPI specification (formerly known as the Swagger specification) is one such solution, but what is Swagger, how does it work, and how can it help you to create top-quality API documentation?
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.
As well as “pro” tools (subscription-based), Swagger offers a popular suite of open-source tools for API development and documentation, including:
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 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 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.
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.
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.
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.
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.
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.
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.
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.
Here are some public Swagger API documentation examples:
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 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.
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.
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.
Writing API documentation in Swagger automates amount of the documentation workload and to a degree makes things much simpler for the Technical Writer, but it is important to remember some of the key aspects of Technical Writing; such as planning your documentation before you start writing, remember who you’re writing for, and make sure that the documentation is kept up to date.
Also Read: 6 Best API Documentation Tools for 2023
The OpenAPI specification and Swagger have been used synonymously for many years, what with it having been the Swagger API specification originally, but since the specification became OpenAPI, Swagger isn’t the only API documentation solution for OpenAPI anymore. Many more tools are now available, and as part of your planning, you should consider whether other tools might be more appropriate too.
Never forget that your API documentation has one aim: To help developers to connect to the API and interact with the data that they need.
Schedule a demo with one of our experts to take a deeper dive into Document360Book A Demo