OpenAPI and Swagger (API First Development)

The Swagger tools, and the OpenAPI format, are an excellent way to document REST API's and even to generate client or server stub libraries to ease implementation. The technology serves two purposes 

                a) standardized documentation for REST API's,

                b) generating code from API documentation in several programming languages.

An OpenAPI file is fairly simple to write, An OpenAPI file allows you to describe your entire API, including:

• Available endpoints (/users) and operations on each endpoint (GET /users, POST /users)
• Operation parameters Input and output for each operation
• Authentication methods   
• Contact information, license, terms of use and other information.

API specifications can be written in YAML or JSON..

What are they?

https://swagger.io/blog/api-design/openapi-driven-api-design/

OpenAPI = Specification (OAS Open API Specification)

Swagger = Tools for implementing the specification

The development of the specification is fostered by the OpenAPI Initiative, which involves more the 30 organizations from different areas of the tech world — including Microsoft, Google, IBM, and CapitalOne. Smartbear Software, which is the company that leads the development of the Swagger tools, is also a member of the OpenAPI Initiative, helping lead the evolution of the specification.

Swagger tools which can be used at different stages of the API lifecycle

Swagger Editor: Swagger Editor lets you edit OpenAPI specifications in YAML inside your browser and to preview documentations in real time.

Swagger UI: Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from an OAS-compliant API.

Swagger Codegen: Allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec.

Swagger Parser: Standalone library for parsing OpenAPI definitions from Java

Swagger Core: Java-related libraries for creating, consuming, and working with OpenAPI definitions

Swagger Inspector (free): API testing tool that lets you validate your APIs & generate OpenAPI definitions from an existing API

SwaggerHub (free and commercial): API design and documentation, built for teams working with OpenAPI.

Eclipse tool to develop swagger:

KaiZen OpenAPI Editor is an Eclipse editor for the industry standard API description language, formerly known as Swagger. It now supports both Swagger-OpenAPI version 2.0 and OpenAPI version 3.0.

Basic Structure of an OpenAPI Specifications file:

Specification documentation:

https://swagger.io/docs/specification/about/

All keywords are case sensitives.

• -          Metadata
• -          Servers
• -          Path
• -          Parameters
• -          Request body
• -          Responses
• -          Input and output models
• -          Authentication

Example:

Generating server-side code:

Swagger-codegen:

                Download the code and build jar or download jar directly from below url

https://github.com/swagger-api/swagger-codegen

https://github.com/swagger-api/swagger-codegen/wiki/server-stub-generator-howto

                java -jar swagger-codegen-cli-3.0.0.jar generate -i api\openapi.yaml -l spring --library spring-mvc -o api\mvc -c api\option.json

JHipster codegen:

Generate a JHipster application with OpenApi Enable. You can configure api and model package

<configuration>

                <inputSpec>${project.basedir}/src/main/resources/swagger/api.yml</inputSpec>

                <generatorName>spring</generatorName>

                <apiPackage>com.first.services.web.rest</apiPackage>

                <modelPackage>com.first.services.web.model</modelPackage>

                <supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>

                <configOptions>

                                <delegatePattern>true</delegatePattern>

                </configOptions>

</configuration>

Write your specification using a tool such as swagger-editor, put it in src/main/resources/swagger/api.yml, then run

./mvnw generate-sources

or

./gradlew openApiGenerate

You can move your generated classes to your src/main/java or keep them in target directory ( target directory classes are in classpath)

After moving the classes to src/main/java rename ApiUtil class to a meaningful name with keeping the reference.

Then implement the “Delegate” interfaces generated in ${buildDirectory}/generated-sources/openapi/src/main/java/${package}/web/api/ with @Service classes.

Change the @RequestMapping("/api") annotation located in com.first.services.web.rest

Create JDL file to create entity object

jhipster import-jdl {fileName}

Map the delegate interface implementations to entity object.