1. apidoc
2. documenting APIs
3. OpenAPI spec and generated reference docs

Overview of REST API specification formats

When I introduced REST APIs, I mentioned that REST APIs follow an architectural style, not a specific standard. Several REST specifications were initially developed to provide standards in the way that REST APIs are described. The initial three specs were OpenAPI (formally called Swagger), RAML, and API Blueprint.

In the early years of specifications, there was healthy competition between the formats. But now the OpenAPI specification is the most popular, with the largest community, momentum, and tooling. Because of this, I spend the most time on OpenAPI in this course. In fact, this entire section focuses on the OpenAPI specification. (I moved RAML and API Blueprint into the Additional resources section at the end.)

“OpenAPI” refers to the specification, while “Swagger” refers to the API tooling that reads and displays the information in the specification. The OpenAPI specification is a vendor-neutral format led by a steering committee comprised of many companies. I’ll dive into both OpenAPI and Swagger in much more depth in the pages to come.

Overall, specifications for REST APIs lead to better reference documentation for your API. Keep in mind that these REST API specifications mostly describe the reference endpoints in an API. While the reference topics are important, you will likely have a lot more documentation to write. (This is why I created an entire section of conceptual topics.)

Nevertheless, the reference documentation that the specification covers often constitutes the core value of your API, since it addresses the endpoints and what they return.

Writing to a specification introduces a new dimension to documentation that makes API documentation substantially unique. By mastering the OpenAPI specification format, you can distinguish yourself in significant ways from other technical writers.