API Development with OpenAPI and Swagger

Building Node.js REST API servers from OpenAPI specifications

(May 24, 2022) OpenAPI specifications are meant to assist creating either server or client API implementations. In this article we will explore quickly implementing server code from an OpenAPI spec, running on Node.js, preferably using TypeScript.

Easily edit or view OpenAPI 3 API specifications using free tools

(May 20, 2022) OpenAPI documents are written in either YAML or JSON and are editable with any programmer's editor. Tools like the Swagger Editor interactively assist with writing OpenAPI specifications by immediately showing errors and interactive API documentation. Since OpenAPI is an open specification, the door is open for any company to develop OpenAPI tools. In this post, we'll go over using the Swagger Editor on the swagger.io website and try some alternatives that will run on your laptop.

Displaying Swagger UI in an HTML page without using server-side services

(May 19, 2022) Among the Swagger Tools is Swagger UI, an excellent tool for browsing an OpenAPI specification, the methods it defineds, and the data models it defines. Swagger UI turns the YAML or JSON specification file into an interactive browsing of the API. In this article we'll go over deploying the Swagger UI documentation viewer in a regular web page.

Create a Spring Boot REST API using Swagger, OpenAPI, to "Generate Swagger OpenAPI REST API documentation for Spring Boot application"

(July 31, 2017)

The Swagger tools, and the OpenAPI format, are an excellent way to document REST API's and even to generate client or server stub libraries to ease implementation. The technology serves two purposes -- a) standardized documentation for REST API's, b) generating code from API documentation in several programming languages. An OpenAPI file is fairly simple to write, you declare REST endpoints, describe the parameters and the request type, and then describe responses. It allows you to define complex object models that can be used either as input to a service, or its output.

Unfortunately the Swagger website doesn't have adequate documentation of using the tools. And it proved difficult to find clear straight-forward tutorials showing how to get started. Even the most powerful tool can be hampered if folks are unable to use it.

The following tutorial is a complete demonstration of, starting from scratch, developing a small Spring Boot service using OpenAPI and the Swagger tools. We show how to go from an OpenAPI spec to generated Spring Boot code, and also how to generate an OpenAPI spec from running Spring Boot code. There are several issues with the workflow of generating code from the OpenAPI spec. It's more effective to instead write the service code, and add in the annotations required for the Swagger tools to generate the OpenAPI spec for you.

With the OpenAPI spec it's easy to produce interactive API documentation that programmers can try out directly in their web browser.