If you manage, develop, or use REST APIs I have a tip for you. Swagger is a framework and toolset that greatly eases the pain of documenting and interacting with your APIs. It’s a swiss army knife for all things APIs and in this post I’ll explain why and how it makes APIs more enjoyable to work with.

We have quite a few APIs here are PLOS. Some are internal, some are exposed to the world. We have APIs for article content, authors, readers, manuscripts, taxonomies, configuration, metrics, reviewer matching and more. They are developed with a breadth of technologies including Java, Python, and Ruby.

Keeping track of how all these APIs work is quite a task. When we had a single API it was documented in a Wiki. As the API grew, the maintenance cost of that document also increased. When we started splitting our mega service into smaller ones, we needed a better way to keep our documentation up to date. Swagger did that and so much more.

At its core, Swagger uses the OpenAPI specification which is a machine readable description of your API. This typically looks like a large JSON or YAML file. The spec itself is not too interesting, but the tooling around it makes the spec incredibly powerful.

For example, one of our internal APIs implements a well defined Java REST specification. We use a library provided by Swagger to autogenerate the swagger spec into JSON from our API. This spec is regenerated every time our project is updated and hosted in a special namespace of our API.

Now that we have a spec, we use the Swagger UI tool which is simply an HTML/Javascript page that parses the spec and displays it as readable documentation. The documentation is not static though. You can actually interact with it and use it to perform API calls through your browser. We deploy these interactive docs with our services and it helps our consumers a lot.

With very little work we were able to provide a huge benefit to our API users. But it doesn’t stop there.

We have many APIs and we also have many apps that use those APIs. The consumer apps can also make use of the spec. Swagger code generators parse the spec and generate client libraries for us. This way our apps don’t have to know about REST at all. They just load a client library and interact with it like an object. The generators support dozens of languages and frameworks out of the box. Or you can use one of the hundreds of community driven ones. Want a command line tool that can tap into all your APIs at your organization at once? The generators can help with that too.

That covers most of how we use it at PLOS, but Swagger can do much more. For example you can write an OpenAPI spec and use a code generator to create scaffolding for a new API, or even mock parts of your API.

Additionally the community behind swagger is an open group of API enthusiasts. I have found that most of the problems I might have with APIs they have solved or are working on it.