Document APIs with Swagger (2/4) — The framework

In this series of articles, I will introduce the different Swagger tools. Swagger is a very handy tool for API documentation. It allows you to generate “living” documentation, so that the documentation is always up to date, which is very difficult to do without this kind of tool. It also allows to generate code automatically, allowing the developer to focus on his core business. Finally, it is based on an open source specification format.

These articles focus on Swagger 2.0, while the 3.0 version (“OpenAPI 3.0.0”) is available.

This article is thus broken down into four parts :

The Swagger framework (https://github.com/swagger-api) includes several sub-projects that meet a specific objective. Here are the ones we will discuss here:

  • Swagger Editor,
  • Swagger UI,
  • Swagger CodeGen.

Swagger Editor

Swagger Editor (https://github.com/swagger-api/swagger-editor) allows to edit specification files in YAML format. In other words, it allows you to create a contract.

Launch Swagger Editor :

The output of the command is:

Then in a web browser, go to http://0.0.0.0:82.

Import specifications

To import the Swagger specification in Yaml format and generate the interactive documentation, you can:

  • copy/paste the content of the Swagger Yaml file,
  • import a file from your local hard drive (File | Import file),
  • import a file from a URL (File | Import URL),

To generate the source code of the :

  • Go to http://0.0.0.0:82
  • copy/paste the content of the Swagger Yaml file,
  • or import a file from your local hard drive (File | Import file),
  • or import a file from a URL (File | Import URL).

Generate the server code

To generate the server source code, use: Generate Server | nodejs-server

Then decompress the generated source code:

Display the contents of the ContactService.js file:

The content of this file is:

Then install the dependencies:

The output of the command is:

Launch the NodeJS server:

This command displays in the terminal:

Client code generation

To generate the client source code use : Generate Client | javascript

Then decompress the generated source code :

The file is unzipped :

Swagger UI

Swagger UI (https://github.com/swagger-api/swagger-ui) is an interactive tool for viewing and executing Swagger specification files. It allows you to publish interactive and attractive API documentation.

You can use android, bash, dar, go, java, jmeter, kotlin, php, python, swift4, or typescript-node.

Launch Swagger UI :

The result of the command is:

Go to http://0.0.0.0:83 to access the Swagger UI user interface.

Swagger Codegen

Swagger Codegen (https://github.com/swagger-api/swagger-codegen) allows to read specification files and generate the API client and server skeleton code in different languages.

For a list of supported languages :

Here is the result of the command:

To validate a specification:

This command returns the following result:

PHP code generation

For PHP:

The output of the command is:

Check that the code has been generated:

This command shows that a directory has been created:

Let’s clean up our directory by deleting the subdirectory out.

Code generation for Python

For Python:

The output of this command is:

Check that the files have been generated:

We can see that files have been generated:

Let’s clean up our directory by deleting the out subdirectory.

Code generation for NodeJS

For NodeJS:

The output of the Docker container gives :

Let’s see the generated files:

The Docker container did generate:

Now you know how to use the different tools of the Swagger framework.

More articles on my blog http://www.DevOpsTestLab.com.

My DevOpsTestLab Youtube channel.

My LinkedIn profile: https://fr.linkedin.com/in/brunodelb

Interests in the full lifecycle: design, Agile Coaching, development, testing, DevOps, Cloud, Management 3.0, ITIL. It defines me.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store