Guide to Swagger Parser

1. Introduction

Swagger is a set of tools used to design, describe and document RESTful APIs.

In this tutorial, we’ll explore how to parse an OpenAPI document file in Java and extract its various components.

2. What Is Swagger?

Swagger is basically an open-source set of rules, specifications, and tools for developing and describing REST APIs. However, with the evolution of new standards and specifications, the specifications are now renamed to OpenAPI Specification (OAS).

The OpenAPI Specification standardizes how to create an API design document. It creates a RESTful interface that we can use to easily develop and consume an API. The API specification effectively maps all the resources and operations associated with it.

An OpenAPI document is a self-contained or composite resource that defines an API along with its various elements. The document may be represented either in JSON or YAML format.

The latest version of OpenAPI Specification is OAS 3.1. It allows us to specify HTTP resources, verbs, response codes, data models, media types, security schemes, and other API components. We can use the OpenAPI definition for generating documentation, code generation, and many other use cases.

On the other hand, Swagger has evolved into one of the most widely used open-source toolsets for developing APIs. It basically provides a complete toolset to design, build, and document APIs.

To validate an OpenAPI document, we use the Swagger Validator tool. Moreover, Swagger Editor provides a GUI-based editor which helps us edit and visualize the API documentation in runtime.

We can easily use the generated OpenAPI documents used with third-party tools like importing to Postman.

3. Using Swagger Parser

Swagger Parser is one of the Swagger tools that help us parse the OpenAPI document and extract its various components. Next, let’s look at how we can implement the parser in Java:

3.1. Dependencies

Before we begin, let’s add the Swagger Parser’s Maven dependency to our project’s pom.xml file:

<dependency>
    <groupId>io.swagger.parser.v3</groupId>
    <artifactId>swagger-parser</artifactId>
    <version>2.1.13</version>
</dependency>

Next, let’s dive into how we can parse an OpenAPI document.

3.2. Sample OpenAPI Documents

Before we begin, we’d need some sample OpenAPI documents that we can parse. Let’s use the following sample OpenAPI YAML document named sample.yml:

openapi: 3.0.0
info:
  title: User APIs
  version: '1.0'
servers:
  - url: https://jsonplaceholder.typicode.com
    description: Json Place Holder Service
paths:
  /users/{id}:
    parameters:
      - schema:
          type: integer
        name: id
        in: path
        required: true
    get:
      summary: Fetch user by ID
      tags:
        - User
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
      operationId: get-users-user_id
      description: Retrieve a specific user by ID

The above YAML is a very simple OpenAPI spec that defines an API that fetches a user’s details by ID.

Similarly, let’s also have an equivalent JSON document file named sample.json:

{
  "openapi": "3.0.0",
  "info": {
    "title": "User APIs",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://jsonplaceholder.typicode.com",
      "description": "Json Place Holder Service"
    }
  ],
  "paths": {
    "/users/{id}": {
      "parameters": [
        {
          "schema": {
            "type": "integer"
          },
          "name": "id",
          "in": "path",
          "required": true
        }
      ],
      "get": {
        "summary": "Fetch user by ID",
        "tags": [
          "User"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "get-users-user_id",
        "description": "Retrieve a specific user by ID"
      }
    }
  }
}

We’ll use these OpenAPI document files for all our coding examples.

Let’s now take a look at how we can parse this document.

3.3. Parsing OpenAPI YAML Document

Firstly, we make use of the OpenAPIParser().readLocation() method to read and parse a YAML or JSON file. This method accepts three parameters:

• String – URL of the file we want to read
• List<AuthorizationValue> – List of authorization headers to be passed if the OpenAPI document to be read is protected
• ParserOptions – additional parsing options as a way to customize the behavior while parsing

Firstly, let’s check the code snippet to read the OpenAPI document from a URL:

SwaggerParseResult result = new OpenAPIParser().readLocation("sample.yml", null, null);

The readLocation() method returns an instance of SwaggerParserResult that contains the parsed result.

Secondly, we’ll use the returned SwaggerParserResult instance to fetch the parsed details:

OpenAPI openAPI = result.getOpenAPI();

The SwaggerParserResult.getOpenAPI() method returns an instance of OpenAPI class. The returned OpenAPI class instance is basically a POJO version of the OpenAPI document.

Lastly, we can now use the various getter methods from the obtained OpenAPI instance to fetch the various components of the OpenAPI document:

SpecVersion version = openAPI.getSpecVersion();

Info info = openAPI.getInfo();

List<Server> servers = openAPI.getServers();

Paths paths = openAPI.getPaths();

3.4. Parsing OpenAPI JSON Document

In a similar fashion, we can also parse an equivalent JSON document file. Let’s parse the sample.json file by passing its file name as the URL:

SwaggerParseResult result = new OpenAPIParser().readLocation("sample.json", null, null);

Moreover, we can even parse OpenAPI Specification document from a String using the OpenAPIParser().readContents(String swaggerString, List<AuthorizationValue> auth, ParseOptions options) method.

Also, we can fetch any validation errors and warnings during the parsing by calling the SwaggerParserResult.getMessages() method. This method returns a list of strings containing the error messages:

List<String> messages = result.getMessages();

4. Conclusion

In this article, we looked at the fundamentals of OpenAPI Specification and Swagger.

We saw how we could parse an OpenAPI document file in Java. We implemented the code to parse both YAML and JSON specification files.

As always, the complete code for all the examples is available over on GitHub.