How to use swagger to document REST API: API first approach

Swagger is a tool that helps you create and document your REST API.

By REST API I mean endpoints and models. By endpoint I mean get, post, put, delete handlers. By model I mead data that pass to and return by an endpoint.

There are two main ways to use swagger in a project:

API first approach
Code first approach

API first approach

The approach is to describe all REST API in a file with help of an editor and then generate all handlers and models for you preferable programming language with help of a swagger-codegen tool.

Let’s define a swagger file (box.yaml) with an endpoint and a model

swagger: "2.0"
info:
  version: "1.0.0"
  title: "REST API example"
paths:
  /box:
    get:
      summary: "get a box"
      description: ""
      produces:
      - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/Box"
definitions:
  Box:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      height:
        type: "integer"
        format: "int32"
      width:
        type: "integer"
        format: "int32"

You can download swagger-codegen from here.

Then run it with help of the following command:

java -jar swagger-codegen-cli-2.3.1.jar generate -i box.yaml -l spring -o ./tmp/java

It specifies the name of a file with REST API (-i box.yaml), a programming language (-l spring) and an output directory with generated code (-o /tmp/java).

You can selectively generate only models (-Dmodels), API (-Dapis) or both (-Dmodels -Dapis) with help of the following flags.

For example to generate only models and API you can use the following flags:

-Dmodels -Dapis

You could generate only interfaces with help of the following command:

-DinterfaceOnly=true

The result command may look like this:

java -jar swagger-codegen-cli-2.3.1.jar generate -i box.yaml -l spring -o ./tmp/java_model_api -Dmodels -Dapis -DinterfaceOnly
=true

The following command will show all avaliable options for a language [https://github.com/swagger-api/swagger-codegen]:

java -jar swagger-codegen-cli-2.3.1.jar config-help -l {lang}

The following command will show all avaliable languages:

java -jar swagger-codegen-cli-2.3.1.jar langs

You can generate code automatically with help of a swagger-codegen-maven-plugin if you want.

Simply add the following piece code to a pom file:

<dependencies>
    <!-- ... -->

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- ... -->
        
        <plugin>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-codegen-maven-plugin</artifactId>
            <version>2.3.1</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/box.yaml</inputSpec>
                <language>spring</language>
                <configOptions>
                    <sourceFolder>src/gen/java/main</sourceFolder>
                    <interfaceOnly>true</interfaceOnly>
                    <java8>false</java8>
                </configOptions>
                <generateApis>true</generateApis>
                <generateApiTests>false</generateApiTests>
                <generateApiDocumentation>false</generateApiDocumentation>
                <generateModels>true</generateModels>
                <generateModelTests>false</generateModelTests>
                <generateModelDocumentation>false</generateModelDocumentation>
                <generateSupportingFiles>false</generateSupportingFiles>
            </configuration>            
        </plugin>
    </plugins>
</build>

Code first approach will be described in the next post.

API first approach

CATALOG

FEATURED TAGS