Advanced Techniques in Go Programming/

...

/

Using Swagger for REST API Documentation

Using Swagger for REST API Documentation

Let’s learn how to use Swagger for REST API documentation.

We'll cover the following...

In this lesson, we’ll discuss the documentation of a REST API. We are going to use the OpenAPI Specification for documenting the REST API. The OpenAPI Specification, which is also called the Swagger Specification, is a specification for describing, producing, consuming, and visualizing RESTful web services.

Put simply, Swagger is a representation of our RESTful API. Swagger reads the appropriate code annotations and creates the OpenAPI file. To be able to document a REST API using Swagger, we basically have two choices. First, writing the OpenAPI Specification file on our own (manually), or adding annotations in the source code that help Swagger generate the OpenAPI Specification file for us (automatically).

Press + to interact

Using go-swagger

We are going to use go-swagger, which brings to Go a way of working with the Swagger API. The extra content for creating the documentation for the REST API is put in the Go source files as Go comments. The utility reads these comments and generates the documentation! However, all comments should follow certain rules and comply with the supported grammar and conventions.

First, we need to install the go-swagger binary by following the instructions found here. Because instructions and versions change from time to time, do not forget to check for updates. The instructions from the previous web page install the swagger binary in /usr/local/bin, which is the appropriate place for external binary files. However, we are free to put it elsewhere as long as the directory we put it in is in our PATH. After a successful installation, running Swagger on the command line should generate the next message, which states the commands that are supported by swagger:

Please specify one command of: diff, expand, flatten, generate, init,
mixin, serve, validate or version

We can also get extra help for each swagger command with the --help flag. For example, getting help for the generate command is as simple as running swagger generate --help:

# swagger generate --help
Usage:
  swagger [OPTIONS] generate <command>
generate go code for the swagger spec file
Application Options:
  -q, --quiet                  silence logs
      --log-output=LOG-FILE    redirect logs to file
Help Options:
  -h, --help                   Show this help message
Available commands:
  cli        generate a command line client tool from the swagger spec
  client     generate all the files for a client library
  markdown   generate a markdown representation from the swagger spec
  model      generate one or more models from the swagger spec
  operation  generate one or more server operations from the swagger spec
  server     generate all the files for a server application
  spec       generate a swagger spec document from a go application
  support    generate supporting files like the main function and the api builder

Documenting the REST API

This section teaches us how to document an existing REST API. For reasons of simplicity, ...