[JAVA] Introduction à Spring Boot x Open API ~ Open API créée avec le modèle d'écart de génération ~

Contexte

Participation à l'événement communautaire Java "JJUG CCC 2019 Fall". L'histoire de la création d'un OpenAPI super simple inspiré du contenu du "développement de serveur API utilisant la spécification OpenAPI 3.0 qui n'est pas Swagger" que j'ai entendu là-bas. (Peu profond)

Ce but

Écrire une API ouverte à l'aide de Spring Boot

Flux de développement utilisant OpenAPI (en gros)

Règle: ** Modèle d'écart de génération ** → Ne modifiez pas le fichier de classe généré automatiquement.

1. Préparez le fichier de définition d'API

Utiliser l'exemple dans OAS (OpenAPISpecification)

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

2. Génération automatique de code à partir de la définition

Utilisez le plug-in de Gradle [openapi-generator-gradle-plugin]. Plug-in Gradle qui génère automatiquement du code à partir du fichier de définition d'API.

build.gradle

plugins {
	id "org.openapi.generator" version "4.2.1"
}

Point 1: Paramètres au moment de la compilation

Défini pour inclure les fichiers de classe générés automatiquement au moment de la compilation

build.gradle

compileJava.dependsOn tasks.openApiGenerate
sourceSets.main.java.srcDir "${openApiGenerate.outputDir.get()}/src/main/java"
sourceSets.main.resources.srcDir 

Point 2: Paramètres d'Openapi Generator

Presque une copie de l'exemple d'exécution de openapi-generator-gradle-plugin est OK. Manipulez simplement le fichier de configuration pour créer une interface.

build.gradle

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

openApiGenerate {
    generatorName = "spring"
    //Paramètres de configuration
    configFile = "$rootDir/specs/config.json".toString()
    //Exemple de spécification d'API
    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
}

La génération automatique de classe est OK avec la tâche de Gradle [openApiGenerate].

Lorsque la tâche est exécutée, le fichier Java suivant est automatiquement généré

3. Implémentation de l'API

Générer un contrôleur en implémentant à partir d'une interface générée automatiquement

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);
	}
}

Achevée! !!

Code complété

https://github.com/harutotanabe09/SpringBootOpenAPIBegin

Bonus: j'ai essayé d'utiliser l'outil de documentation OpenAPI

Les documents sont automatiquement générés à l'aide de l'outil de document OpenAPI (redoc).

• Prérequis: Docker est inclus

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

http://localhost/

Image de sortie: affichez les paramètres d'API et renvoyez les valeurs sur un écran facile à lire basé sur le fichier de définition

Matériel de référence

Développement de serveur API avec la spécification OpenAPI 3.0, pas Swagger https://www.slideshare.net/techblogyahoo/swagger-openapi-specification-30-api