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:
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.
