[JAVA] Introduction to Spring Boot x OpenAPI ~ OpenAPI made with Generation gap pattern ~

background

Participated in the Java community event "JJUG CCC 2019 Fall". The story of creating a super-simple OpenAPI inspired by the content of the "API server development using OpenAPI Specification 3.0 that is not Swagger" that I heard there. (Shallow)

This goal

Write OpenAPI using Spring Boot

Development flow using OpenAPI (roughly)

image.png

Rule: ** Generation gap pattern ** → Do not edit the automatically generated class file.

1. Prepare API definition file

Use the sample in OAS (OpenAPI Specification)

https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml

2. Automatic code generation from definition

Use Gradle plugin [openapi-generator-gradle-plugin]. Gradle plugin that automatically generates code from API definition file.

build.gradle


plugins {
	id "org.openapi.generator" version "4.2.1"
}
Point 1: Compile settings

Set to include automatically generated class files at compile time

build.gradle


compileJava.dependsOn tasks.openApiGenerate
sourceSets.main.java.srcDir "${openApiGenerate.outputDir.get()}/src/main/java"
sourceSets.main.resources.srcDir 
Point 2: Openapi Generator settings

The execution example of openapi-generator-gradle-plugin can be almost copied. Just manipulate the config file to create an interface.

build.gradle


//https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-gradle-plugin

openApiGenerate {
    generatorName = "spring"
    //Config settings
    configFile = "$rootDir/specs/config.json".toString()
    //Sample API specification
    inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString()
    outputDir = "$buildDir/generated".toString()
    apiPackage = "org.openapi.example.api"
    invokerPackage = "org.openapi.example.invoker"
    modelPackage = "org.openapi.example.model"
    configOptions = [
        dateLibrary: "java8"
    ]
    systemProperties = [
        modelDocs: 'false'
    ]
}

config.json


{
  "interfaceOnly": true
}

Automatic class generation is OK with Gradle task [openApiGenerate].

スクリーンショット 2019-11-24 9.40.36.png

When the task is executed, the following Java files are automatically generated

image.png

3. API implementation

Generate a controller by implementing from the automatically generated interface

PetsApiController.java


@RestController
public class PetsApiController implements PetsApi{
	@Override
	public ResponseEntity<List<Pet>> listPets(@Valid Integer limit) {
		System.out.println("Here list pet");
		return new ResponseEntity<>(HttpStatus.OK);
	}
}

Complete! !!

Completed code

https://github.com/harutotanabe09/SpringBootOpenAPIBegin

Bonus: I tried using the OpenAPI documentation tool

Documents are automatically generated using the OpenAPI Document Tool (redoc).

docker run -it --rm -p 80:80 \
  -v $(pwd)/specs/petstore-v3.0.yaml:/usr/share/nginx/html/swagger.yaml \
  redocly/redoc

http://localhost/

Output image: Output API parameters and return values on an easy-to-read screen based on the definition file

image.png

Reference material

API server development with OpenAPI Specification 3.0, not Swagger https://www.slideshare.net/techblogyahoo/swagger-openapi-specification-30-api

Recommended Posts

Introduction to Spring Boot x OpenAPI ~ OpenAPI made with Generation gap pattern ~
[Introduction to Spring Boot] Authentication function with Spring Security
Introduction to Spring Boot ① ~ DI ~
Introduction to Spring Boot ② ~ AOP ~
Introduction to Spring Boot Part 1
[Introduction to Spring Boot] Form validation check
Use cache with EhCashe 2.x with Spring Boot
Introduction to Java development environment & Spring Boot application created with VS Code
How to use MyBatis2 (iBatis) with Spring Boot 1.4 (Spring 4)
How to use built-in h2db with spring boot
Try to implement login function with Spring Boot
An introduction to Spring Boot + in-memory data grid
[Java] Hello World with Java 14 x Spring Boot 2.3 x JUnit 5 ~
Try to automate migration with Spring Boot Flyway
[Java] Article to add validation with Spring Boot 2.3.1.
I wanted to gradle spring boot with multi-project
Settings for connecting to MySQL with Spring Boot + Spring JDBC
Automatically map DTOs to entities with Spring Boot API
A memorandum of addiction to Spring Boot2 x Doma2
SSO with GitHub OAuth in Spring Boot 1.5.x environment
[Introduction to Spring Boot] Submit a form using thymeleaf
Nginx + Spring Boot parrot return LineBot made with VPS
How to boot by environment with Spring Boot of Maven
Attempt to SSR Vue.js with Spring Boot and GraalJS
Connect Spring Boot and Angular type-safely with OpenAPI Generator
Download with Spring Boot
Output embedded Tomcat access log to standard output with Spring Boot
Extract SQL to property file with jdbcTemplate of spring boot
Until INSERT and SELECT to Postgres with Spring boot and thymeleaf
Connect to database with spring boot + spring jpa and CRUD operation
Flow until output table data to view with Spring Boot
I tried to get started with Swagger using Spring Boot
Introduction of library ff4j that realizes FeatureToggle with Spring Boot
Try Spring Boot from 0 to 100.
Generate barcode with Spring Boot
Implement GraphQL with Spring Boot
Get started with Spring boot
Introduction to Ratpack (7) --Guice & Spring
Hello World with Spring Boot!
Run LIFF with Spring Boot
SNS login with Spring Boot
File upload with Spring Boot
Spring Boot starting with copy
Generation gap with new engineers
Spring Boot starting with Docker
Hello World with Spring Boot
Set cookies with Spring Boot
Use Spring JDBC with Spring Boot
Add module with Spring Boot
Getting Started with Spring Boot
Create microservices with Spring Boot
Send email with spring boot
How to realize huge file upload with TERASOLUNA 5.x (= Spring MVC)
02. I made an API to connect to MySQL (MyBatis) from Spring Boot
How to create your own Controller corresponding to / error with Spring Boot
I made a simple search form with Spring Boot + GitHub Search API.
Sample code to unit test a Spring Boot controller with MockMvc
Use Basic Authentication with Spring Boot
gRPC on Spring Boot with grpc-spring-boot-starter
Create an app with Spring Boot 2
Hot deploy with Spring Boot development