OpenAPI Documentation (Swagger 2.0)

Open API Specification (OAS) Swagger 2.0 is a full package for RESTful API Documentation. It defines a standard, language-agnostic interface for RESTful API Documentation. The Swagger documentation is defined for Consumer, to understand the capabilities of the services and interact with minimum efforts from client-side and without any client implementation.

In this post, we will see how we can execute programs for RESTful APIs Documentation first with Spring Boot, JPA, and H2 Database and second with NodeJS, ExpressJS, and MongoDB.

  • Prerequisite

For the Spring Boot Application:
Java must be installed first.
You will also need Maven Setup done already on your machine.
You will need an IDE like Eclipse to build and execute the project.


Find the Source Code on GitHub: Spring Boot Swagger2 App.

For NodeJS, Express and MongoDB Application:
NodeJS must be installed first.
You will also need the MongoDB Setup on your machine.

Find the Source Code on GitHub: NodeJS Express Swagger2 App.

  • Spring Boot REST API Documentation (Swagger 2.0) Program

Once above pre-requisites are done, use the GitHub project to clone and execute. Check program instructions as below.

  1. Once the JDK and Maven setup is done. In any of the empty directory checkout the Git project for SpringBootSwagger2. This will be your workspace with eclipse to execute or modify the SpringBootSwagger2 Java Source code.

    Spring Boot REST API Swagger2 API Doc Project

  2. The SpringBootSwagger2 program will be created in Eclipse and it will have /src/main/java/
    folder for writing java source code.

    Now, run the Maven command from this Project folder to build the project and run, mvn spring-boot:run.

    Alternatively, the package can be created and run using below command.
    mvn package
    java -jar target/SpringBootSwagger2-0.1.jar

    Then use the URL
    http://localhost:8090/swagger-ui.html to execute
    and see the result on the browser. The port configured for this Spring Boot App is 8090.
    See below the example screenshot of how the Swagger 2.0 Documentation UI will look like.

    Spring Boot Swagger2 Application Swagger UI Screen.

    Spring Boot Swagger2 Application Swagger UI Screen

    Using the UI now basic CRUD operations can be performed, without any functional understanding of the application as well as without any client implementation.
    So here we are done with the program for Spring Boot with Swagger 2.0 API Documentation.

  • NodeJS, Express and MongoDB REST API Documentation (Swagger 2.0) Program

Once above pre-requisites are done, use the GitHub project to clone and execute. Check program instructions as below.

  1. Once the NodeJS setup and MongoDB setup is done. In any of the empty directory checkout the Git project for express-swagger-app. This will be the workspace with NodeJS to execute or modify the express-swagger-app Source code. Recommended is Visual Studio Code Development Tool.

    NodeJS ExpressJS REST API Swagger2 API Doc Project

  2. The express-swagger-app program can be modified using any HTML and JavaScript Editor like Visual Studio Code or Atom or Sublime etc.
    Once the folder is checkout from GitHub, cd into that folder and then execute npm install to install required Node Modules for executing the Application.

    Before you run this Application, make sure that MongoDB database service is also running.
    Once the required modules are installed, the Application is ready to run using npm run dev npm command.
    Then use the URL
    http://localhost:3000/api/v1/api-docs/ to execute
    and see the result on the browser. The port configured for this NodeJS App is 3000.
    See below the example screenshot of how the Swagger 2.0 Documentation UI will look like.

    NodeJS Express Swagger2 Application Swagger UI Screen.

    NodeJS Express Swagger2 Application Swagger UI Screen

    Using the UI now basic CRUD operations can be performed, without any functional understanding of the application as well as without any client implementation.
    So here we are done with the very first program for NodeJS and Express with MongoDB and last but not the least Swagger 2.0 API Documentation.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.