[JAVA] Einführung in Spring Boot x Offene API ~ Offene API, erstellt mit Generationslückenmuster ~

Hintergrund

Teilnahme an der Java-Community-Veranstaltung "JJUG CCC 2019 Fall". Die Geschichte der Erstellung einer supereinfachen OpenAPI, inspiriert vom Inhalt der "API-Serverentwicklung mit OpenAPI Specification 3.0, die nicht Swagger ist", die ich dort gehört habe. (Flach)

Dieses Ziel

Schreiben Sie die Open API mit Spring Boot

Entwicklungsablauf mit OpenAPI (ungefähr)

Regel: ** Generationslückenmuster ** → Bearbeiten Sie die automatisch generierte Klassendatei nicht.

1. Bereiten Sie die API-Definitionsdatei vor

Verwenden Sie das Beispiel in OAS (OpenAPISpecification)

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

2. Automatische Codegenerierung aus der Definition

Verwenden Sie das Plugin von Gradle [openapi-generator-gradle-plugin]. Gradle-Plug-In, das automatisch Code aus der API-Definitionsdatei generiert.

build.gradle

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

Punkt 1: Einstellungen zur Kompilierungszeit

Legen Sie fest, dass beim Kompilieren automatisch generierte Klassendateien eingeschlossen werden sollen

build.gradle

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

Punkt 2: Openapi Generator Einstellungen

Fast eine Kopie des Ausführungsbeispiels des openapi-generator-gradle-plugins ist in Ordnung. Bearbeiten Sie einfach die Konfigurationsdatei, um eine Schnittstelle zu erstellen.

build.gradle

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

openApiGenerate {
    generatorName = "spring"
    //Konfigurationseinstellungen
    configFile = "$rootDir/specs/config.json".toString()
    //Beispiel-API-Spezifikation
    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
}

Die automatische Klassengenerierung ist mit Gradles Aufgabe [openApiGenerate] in Ordnung.

Wenn die Aufgabe ausgeführt wird, wird automatisch die folgende Java-Datei generiert

3. API-Implementierung

Generieren Sie einen Controller, indem Sie ihn über eine automatisch generierte Schnittstelle implementieren

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

Komplett! !!

Code abgeschlossen

https://github.com/harutotanabe09/SpringBootOpenAPIBegin

Bonus: Ich habe versucht, das OpenAPI-Dokumentationstool zu verwenden

Dokumente werden automatisch mit dem OpenAPI-Dokumententool (Redoc) generiert.

• Voraussetzung: Docker ist enthalten

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

http://localhost/

Ausgabebild: Ausgabe von API-Parametern und Rückgabewerten auf einem übersichtlichen Bildschirm basierend auf der Definitionsdatei

Referenzmaterial

API-Serverentwicklung mit OpenAPI Specification 3.0, nicht Swagger https://www.slideshare.net/techblogyahoo/swagger-openapi-specification-30-api