What is Swagger?

Swagger is a suite of tools to generate and represent RESTful APIs. It promotes the OpenAPI 2.0 spec which describes an API using JSON representation in a specification file called swagger.json. Since YAML is a superset of JSON, the specification file can conform to YAML.

In my projects, I want to be able to generate swagger.json from an annotated codebase to serve using Swagger UI.

Swagger Tools

  • go-swagger
    • enables generating a Go client or server from an existing Swagger spec
    • can scan an annotated codebase and generate a Swagger spec
  • Swagger UI
    • serves visual documentation of an API based on a given Swagger spec

Generating a Swagger spec

go-swagger is a CLI tool. The following is an example command for generating a Swagger spec

swagger generate spec -o ./swagger.json

Installing Swagger UI in a Go application

Based on the installation docs Swagger UI can be served as part of an application using plain HTML/CSS/JS.

How to serve plain HTML Swagger UI

The folder /dist includes all the HTML, CSS and JS files needed to run SwaggerUI on a static website or CMS, without requiring NPM.

  1. Download the latest release.
  2. Copy the contents of the /dist folder to your server.
  3. Open index.html in your HTML editor and replace “https://petstore.swagger.io/v2/swagger.json” with the URL for your OpenAPI 3.0 spec.

What is the purpose?

Reading and writing code is a big part of my daily life and the opportunity to put things together in Go is a fun break from the enterprise application development I do at C Spire. Swagger UI is a tool we use in our Spring/Spring Boot applications to easily share our API documentation with each other and the teams which integrate with us. This post is my personal documentation for how to integrate a tool I know and love in a new programming language.

Michael Lamb is a software engineer for privately-held telecommunications and technology company C Spire, headquartered in Ridgeland, Mississippi. He is a resident of Jackson, Mississippi, with his two cats and many plants. He graduated from Mississippi State University with a bachelor of science in Software Engineering. He is happily employed full-time creating microservices using Java and Spring technologies but is open to consulting.
© Copyright 2021