Home » Enterprise Java » Swagger Inflector Tutorial

About Mohammad Meraj Zia

Senior Java Developer

Swagger Inflector Tutorial

In this article, we will expalin the Swagger Inflector.

1. Introduction

The OpenAPI specification defines the standard of describing HTTP API for any project. This is programming-language agnostic. This helps humans and computers to know about the System/API without the need to look into the code. If the specification is properly implemented it helps a consumer to understand the interaction with the remote system effectively without much hassle.

OpenAPI specification can be compared to an Interface in Java. Interfaces in Java define the contract between the client and the server. It tells the caller what it needs to send and the expected value which will be returned. This helps the caller to reduce the guesswork. Similarly, OpenAPI is a specification that defines how to document your HTTP API so that the consumer of your API has to do minimal guesswork.

One of the big use cases for a machine-readable API definition is to automatically generate the Client code. The OpenAPI documents are generally described in YAML or JSON. The best part is that these documents can be created statically or generated at runtime. One this to note is that OpenAPI can not be integrated with all the available HTPP API implementations – but they are available for RESTful HTTP Apis. The current version of OpenAPI specification is 3.1.0.

2. Swagger Inflector

Swagger Inflector is a relatively new project from Swagger which helps in writing APIs. It is still in the preview stage. The main aim is to use the design-first way to code APIs in Java.

First, you need to create your swagger specification using JSON(JavaScript Object Notation) or YAML. You can also use the Swagger editor to build out the definition of your APIs.

Run the below command to download the project:

curl -L https://raw.githubusercontent.com/swagger-api/swagger-inflector/master/setup.sh | project=swagger-inflector-example bash

Below is the output of running the above command:

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  1579  100  1579    0     0   3967      0 --:--:-- --:--:-- --:--:--  3967
fetching setup files from swagger-api/swagger-inflector/master
...fetching editor webapp
...fetching editor scripts
...fetching inflector configuration
...fetching project pom
...fetching web.xml
done!  You can run swagger editor as follows:
./editor.sh
then open a browser at open http://localhost:8000

you can run your server as follows:
mvn package jetty:run

and your swagger listing will be at http://localhost:8080/{basePath}/openapi.json

Now run the below command to start the swagger editor:

./editor.sh

Below is the output of running the above command:

2021-05-31 11:40:25.740:INFO::main: Logging initialized @1051ms to org.eclipse.jetty.util.log.StdErrLog
2021-05-31 11:40:25.761:INFO:oejr.Runner:main: Runner
2021-05-31 11:40:26.101:INFO:oejs.Server:main: jetty-9.4.11.v20180605; built: 2018-06-05T18:24:03.829Z; git: d5fc0523cfa96bfebfbda19606cad384d772f04c; jvm 11.0.9.1+12-LTS
2021-05-31 11:40:28.399:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
2021-05-31 11:40:28.399:INFO:oejs.session:main: No SessionScavenger set, using defaults
2021-05-31 11:40:28.418:INFO:oejs.session:main: node0 Scavenging every 660000ms
11:40:29,408 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback.groovy]
11:40:29,408 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Could NOT find resource [logback-test.xml]
11:40:29,409 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Found resource [logback.xml] at [file:/private/var/folders/bz/smf4p4_d39dchlz03l4bfv640000gn/T/jetty-0.0.0.0-8000-swagger-editor.war-_-any-15915355446605046659.dir/webapp/WEB-INF/classes/logback.xml]
11:40:29,515 |-INFO in ch.qos.logback.classic.joran.action.ConfigurationAction - debug attribute not set
11:40:34,545 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - About to instantiate appender of type [ch.qos.logback.core.ConsoleAppender]
11:40:34,550 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - Naming appender as [STDOUT]
11:40:34,630 |-WARN in ch.qos.logback.core.ConsoleAppender[STDOUT] - This appender no longer admits a layout as a sub-component, set an encoder instead.
11:40:34,630 |-WARN in ch.qos.logback.core.ConsoleAppender[STDOUT] - To ensure compatibility, wrapping your layout in LayoutWrappingEncoder.
11:40:34,630 |-WARN in ch.qos.logback.core.ConsoleAppender[STDOUT] - See also http://logback.qos.ch/codes.html#layoutInsteadOfEncoder for details
11:40:34,631 |-INFO in ch.qos.logback.classic.joran.action.LoggerAction - Setting level of logger [io.swagger.inflector] to ERROR
11:40:34,631 |-INFO in ch.qos.logback.classic.joran.action.LoggerAction - Setting level of logger [io.swagger.controllers.SpecsController] to INFO
11:40:34,631 |-INFO in ch.qos.logback.classic.joran.action.RootLoggerAction - Setting level of ROOT logger to ERROR
11:40:34,631 |-INFO in ch.qos.logback.core.joran.action.AppenderRefAction - Attaching appender named [STDOUT] to Logger[ROOT]
11:40:34,632 |-INFO in ch.qos.logback.classic.joran.action.ConfigurationAction - End of configuration.
11:40:34,635 |-INFO in ch.qos.logback.classic.joran.JoranConfigurator@a7e2d9d - Registering current configuration as safe fallback point

loading inflector config from editor/inflector.yaml
2021-05-31 11:40:36.322:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@534df152{/,file:///private/var/folders/bz/smf4p4_d39dchlz03l4bfv640000gn/T/jetty-0.0.0.0-8000-swagger-editor.war-_-any-15915355446605046659.dir/webapp/,AVAILABLE}{file:///Users/ziameraj16/study/JCG/swagger-inflector/editor/swagger-editor.war}
2021-05-31 11:40:36.428:INFO:oejs.AbstractConnector:main: Started ServerConnector@6b4283c4{HTTP/1.1,[http/1.1]}{0.0.0.0:8000}
2021-05-31 11:40:36.429:INFO:oejs.Server:main: Started @11752ms

Now open your favourite browser and navigate to http://localhost:8000. You will see a screen like below:

Swagger Inflector - editor
Figure 1. Swagger Editor

To run the server run the below command:

mvn package jetty:run

3. Summary

In this article, we discussed the Swagger Inflector project. First, we looked at what OpenAPI specification is and what it is used for. Then we discussed how to download and run the Swagger Inflector project which can be used for writing APIs for the project. Inflector uses a single YAML file for configuration. The default file is inflector.yaml but it can be overridden by setting a system property when starting the JVM.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

 

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

 

and many more ....

 

Receive Java & Developer job alerts in your Area

 

Subscribe
Notify of
guest

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

0 Comments
Inline Feedbacks
View all comments