Automation
Rswag: Automated API Documentation
Summarized using AI
Rswag: Automated API Documentation
by Sarah ReidIn her talk at RubyConf 2021, Sarah Reid addresses the crucial issue of API documentation and introduces Rswag as a solution to automate and improve API documentation practices. She emphasizes that good documentation is vital for any successful software application, particularly for APIs, which can often feel like 'black boxes' for developers due to insufficient documentation, leading to inefficiencies and frustrations.
Key points discussed in the presentation include:
- Importance of Documentation: Reid relates her firsthand experiences of struggling with poor documentation, highlighting how effective documentation enhances efficiency and developer experience. Great code is rendered useless without corresponding documentation.
- Common Documentation Problems: She shares her team's experiences with outdated and inaccurate documentation, stating that human error significantly affects documentation quality. Only the engineers can keep it updated, which places a heavy burden on them.
- Introduction to Rswag: Rswag is a tool that integrates with Rails and uses the OpenAPI specification to generate API documentation from written specs. Reid explains how it binds the API and its documentation together, ensuring synchronization and reducing discrepancies.
- OpenAPI Specification: She explains the OpenAPI standard as a language-agnostic interface that provides a consistent way to describe the capabilities and responses of RESTful APIs, allowing developers to naturally understand the service without inspecting code or network traffic.
- Demonstration of Rswag: Reid showcases Rswag in action, demonstrating how easy it is to generate documentation through simple integration. She illustrates adding an attribute to an API response and how running Rswag updates the documentation automatically.
- Swagger UI: The presentation highlights the interactive interface generated from the API schema, allowing developers and users to test API endpoints directly from the documentation, facilitating smoother interactions and debugging.
- Conclusion: Reid urges engineers to consider automating their API documentation to save time and reduce the frustration associated with maintaining documentation, ultimately enhancing the user experience and increasing API adoption.
In conclusion, Sarah Reid's presentation provides a compelling case for using Rswag to alleviate the burdens of API documentation, reinforcing that documentation can and should be automated for better software development practices.
00:00:10
Hi everyone, my name is Sarah and I am a software engineer at Doximity. It is a privilege to speak at RubyConf this year, and it's a significant milestone for me. My first RubyConf was in Cincinnati in 2016.
00:00:21
At that RubyConf, Doximity had a booth there. It was the place where I first learned about Doximity. I got to meet a lot of their engineers who were manning the booth. They were really friendly and intelligent, and left a good impression on me. At the time, I was working at a different company, but two years later, when I was job searching, Doximity came immediately to mind.
00:00:39
The great thing is, now five years later, I obviously work here, but I also still work with many of the people I met that day. I think that really speaks to the strength of the company and our engineering culture here. Now, I have come full circle because Doximity has given me the opportunity to speak at RubyConf and share a little bit of what I've learned during my time here.
00:01:05
Today, I'm going to talk about how to automate your API documentation using Rswag. But first, let's talk for a moment about documentation. You probably already know this, but documentation is important.
00:01:23
This is a subject that is near and dear to my heart, having struggled with undocumented solutions and problems. I have faced situations where I was trying to fix a bug or an error that kept happening, and no amount of Googling was going to find an answer for this. I really had to dig in and find out what was going on underneath the hood.
00:01:53
I know the value of having an answer quickly at hand for a problem like that. Stack Overflow is a great example of this. When I have a problem, Stack Overflow usually has the answer because it's documented. It has been written down so that generations that follow in our footsteps will know how to fix that 'n plus one' issue or just execute better.
00:02:07
Good documentation provides the critical information people need to work effectively at their jobs. The more you write down about these processes or hard lessons that you've learned, the more it increases the efficiency and effectiveness of your peers around you. In the case of APIs, it's even more critical; the documentation you write for your API reflects how your application operates.
00:02:38
If your documentation is inadequate, your application is going to feel that way too. It doesn't matter how great the code is; if the documentation is poor, it will be so difficult to adopt. You know this because you’ve been there. You’ve experienced that one gem or library that is poorly documented, making it hard to get it to do what you need, forcing you to dig into the code to see what it’s even doing.
00:03:05
Without documentation, your product becomes unusable. Let me discuss a common situation we encountered, which is a problem I have seen throughout my career. You have your codebase, this majestic application that has all sorts of amazing features. It can solve all sorts of problems; it's efficient, scalable, and easy to maintain. All of your web developers love working on this application because the code is so great. However, then there's your documentation.
00:03:41
Your documentation is totally isolated, standing alone. There’s no connection between the code and the documentation; they don’t know anything about each other. The only thing that keeps that documentation and your application in sync is you, the engineer. You are the only thing holding this together, and the success of the product depends on you.
00:04:02
And that's a lot of pressure because documentation is hard. With a human being as the catalyst for our documentation, it ends up reflecting the same flaws we have as humans—it will have inaccuracies, it will become outdated, and it will be hard to understand. Even more so, the limitations we have around writing documentation lead to these issues.
00:04:51
So that's where Rswag comes in, which I am going to discuss today. First, I’ll give you a quick agenda: I'll cover a bit of background about the challenges we faced and discuss our team to give you an idea of where we’re coming from. Then, we'll look at what Rswag is and see Rswag in action.
00:05:18
To begin, Doximity is a professional medical network for physicians. We have over 1.9 million users, and over 80 percent of all U.S. doctors are on our platform. Doctors use our platform not only to network with other medical professionals but also to keep up with the latest medical news. We have a news feed, a telehealth calling feature, and so much more.
00:05:50
Our telehealth team, which I work on, handles millions of telehealth calls—both voice and video—per week from hundreds of thousands of medical professionals. Some of our products include a voice feature where physicians can call their patients from our application; they can also conduct video calls and send secure text messages to patients.
00:06:08
Being both mobile and desktop friendly means we have a variety of platforms supported. Our team comprises Ruby on Rails developers, Vue engineers, and iOS and Android developers. The Ruby on Rails developers, whom I will refer to as web devs throughout the talk, handle the backend API, which is critical for managing all these features. It houses all the data and serves the mobile clients and the Vue front-end.
00:06:55
If you want to start a telehealth call, send secure text messages to patients, or anything in between, you must have the backend to do it. This necessitates that our documentation is absolutely critical; it has to be accurate and up to date for these other engineers to be able to do their jobs effectively.
00:07:43
Thankfully, our mobile engineers were honest enough to tell us that our documentation was inadequate. The struggle was not limited to the mobile side; it was an issue on the web development side as well. From the web dev perspective, writing documentation was not a good experience. It was hard to get things to render and hard to even figure out the syntax needed to write this documentation because the tool we were using was itself not well documented.
00:08:10
It was easy to break without realizing it, which meant you could ship some document changes thinking they worked, but nothing would indicate otherwise. Moreover, it became easy to forget to update documentation after endpoint tweaks, especially when you’re in the heat of the moment trying to get a feature out quickly.
00:09:01
On the mobile dev side, the situation was even worse because we weren’t producing quality documentation. What they received was either insufficient or delayed documentation, and they sometimes encountered inaccuracies due to those human qualities: no matter how much you strive for accuracy, critical pieces of information can be overlooked, or there might be no documentation at all.
00:09:36
So we decided to invest some time to rectify this problem. Here were our criteria for improvement: First, the API documentation cannot drift away from the implementation. This was crucial because we wanted our API documentation and our API to be bound together.
00:09:55
Additionally, we envisioned the availability of negative feedback within a test suite. It would be great to have tools to check if our documentation differed from the functionality of the API. If it did, we wanted that test to fail, allowing us to know about the discrepancies and correct them.
00:10:44
We also wanted the tooling to be both client and server friendly. That means providing better, thorough documentation for our mobile engineers while ensuring our web devs could write documentation without friction.
00:11:12
We looked at several tools and ultimately landed on Rswag.
00:11:30
So, what is Rswag? Rswag is a Ruby gem that utilizes the OpenAPI specification. If you're unfamiliar with that, I'll explain shortly. It provides an interactive UI for viewing API documentation, and it generates that API documentation from specs.
00:11:49
That's right—specs that write documentation for you. The way this works is Rswag extends our RSpec. When you write an Rswag spec, you aim first to get them passing. Once your specs are passing, you can 'swaggerize' your specs, and Rswag will generate an OpenAPI specification-compliant schema. That schema can be used for various purposes.
00:12:29
The GIF on the right shows an example of what can be an outcome of that schema. This UI was generated from the schema and reflects what we have in production for our telehealth APIs.
00:12:57
When you swaggerize those specs, they execute real HTTP requests, capture the responses, and put them into the schema. Now, let's dive into the nuts and bolts of how this works, specifically the OpenAPI specification.
00:13:36
This is a standardized, language-agnostic interface to RESTful APIs, which allows both humans and computers to discover and understand the capabilities of the service without requiring access to source code documentation or inspecting network traffic.
00:14:09
Previously, our mobile engineers had to look at source code or inspect network traffic to understand what was going on with our APIs. Now, they don’t have to.
00:14:21
The OpenAPI specification produces either a JSON schema or YAML. All of your documentation is contained within a JSON schema based on the OpenAPI specification standard, allowing the use of various tools.
00:14:45
For instance, I have a blog API with an articles controller. If I want to look at a list of articles, I have a GET /articles API endpoint that returns a list of JSON articles.
00:15:08
When the API returns a response, it includes fields like author, title, body, and more. When this is converted into an OpenAPI specification-compliant schema, it looks something like what is shown on the right.
00:15:45
Although it may seem text-heavy, you can see that the GET /articles path lines up with the expected HTTP method. It’s expected to return JSON, and an example of that response is provided. This example mirrors what your API is delivering, adding great value to your clients.
00:16:15
This JSON or YAML file can accomplish a lot more than just displaying a Swagger UI. For instance, you can generate mock servers based on this schema that will provide example responses as detailed in your OpenAPI specification.
00:16:44
Furthermore, you can generate code to interact with these APIs, which saves a lot of manual work. Instead of writing code by hand, you can utilize a code generator that will produce Ruby code, and this can also apply to other platforms, which is excellent for mobile engineers.
00:17:14
Before delving deeper, let's clarify what Rswag actually is. Rswag stands for Swagger. Swagger originally provided the specification, but they have since adopted the OpenAPI specification, along with a suite of open-source tools for API design and documentation.
00:17:42
These tools allow you to create API documentation and display it, which is what we're doing with Rswag. Now, let’s explore Rswag in action.
00:18:08
I have a public GitHub repository called rswag-blog-api. Feel free to clone it locally and follow along to see what Rswag can do. You can try writing some tests and creating more documentation around it.
00:18:39
This repository features a simple example with one article model and an articles controller, primarily focused on showing the Rswag integration you can play with.
00:19:03
Before diving into the demo, I want to discuss Rswag specs since there is a minor learning curve, and it doesn't follow RSpec specs precisely.
00:19:22
To get an Rswag spec working, we need four components. First, we define the path—here’s an example taken straight from the GitHub codebase: /articles/id, which corresponds to the show action for a given article.
00:19:46
Second, we need to define the operation, which is the HTTP method you're using. It should be compatible with GET, POST, PUT, PATCH, DELETE; in this case, we are testing the GET method for /articles/id.
00:20:18
The third requirement is the expected response. Are we testing for a successful response or an error, like a 422 validation error? Finally, the most important part is running the test.
00:20:54
The run test command tells Rswag to create and execute a corresponding example. It checks that the specified path exists, that it responds to GET requests, and that the response is a 200. If any of this is different, even if it's a 201 instead of a 200, the spec fails, and the documentation won't be written to your schema.
00:21:19
Now let's get into the demo. This is the same OpenAPI schema I shared in my slides, just in a different color.
00:21:39
This shows the index action that displays an array of articles. You can see the attributes like author, title, and body. I want to demonstrate the power of automatically generating API documentation.
00:22:07
This entire document was automatically generated from our Rswag specs. I won't go into too much detail, but this segment of documentation was produced from Rswag specs, illustrating how easy it is to automate documentation.
00:22:45
If I add an attribute to the article model, the documentation will also need to be updated. For instance, I’ll add a 'published' attribute that is set to a boolean value of true. Every output from this API now includes the 'published' field.
00:23:35
In real life, if I forget to update the documentation, it would become inconsistent. All I have to do is run the 'swag' process. The command I execute is 'rake rswag:specs:swaggerize' with a flag to write to my schema file.
00:24:01
Once I execute that, it captures the HTTP responses, and if everything is successful, the published field will be reflected in the schema. Upon refreshing the article page, we can see that the 'published' field is now included.
00:24:31
This change is not only accurate for this index action but extends throughout the entire documentation. It works the same way if you remove fields. If I remove the 'published' field and re-run the swagger process, it won't appear in the documentation anymore.
00:24:56
This automatic updating of documentation is powerful, and I wish I had more time to delve deeper. Let's look at the Swagger UI, which boasts many great features. Everything is generated from that schema, which means it's reliable and up-to-date.
00:25:22
You can see all the endpoints generated, and your engineers, clients, or teams can utilize this UI. It allows you to execute actions against a server, making it easy to test functionalities.
00:25:48
My Ruby on Rails server is running at localhost:3000. I can execute GET requests to see all the articles in my database, and I can create or edit records seamlessly through this interface.
00:26:25
It generates response details and even allows modifications to the existing articles with ease, providing immediate feedback and results for the engineers.
00:26:47
There are many more advanced features available that I do not have the time to discuss today. For example, schema validation can ensure that your JSON responses maintain the expected structure, and Rswag can also efficiently handle authorization.
00:27:24
In conclusion, whether or not you decide to use Rswag (though I encourage you to try it), I hope you take away the message that your documentation can be automated. This not only saves time and effort but also improves the user experience and increases the adoption of the APIs you're developing, along with the fantastic code you write. Thank you for your time. If you are attending in person, we have a booth; please check it out and connect with our engineers and recruiters.
00:29:00
I am presenting virtually, so feel free to DM me during RubyConf. Also, we're hiring! If what we do interests you or if you’d like to work with people like me or the engineers at Doximity, please check out workout.doximity.com. We have a wide variety of openings in Ruby on Rails, site reliability, mobile, and more. It would be fantastic to have you. Thank you very much, and enjoy the rest of RubyConf!
Explore all talks recorded at RubyConf 2021
+92