Documenteren van een Spring REST API met OpenAPI 3.0

REST Top

Ik heb zojuist het nieuwe aangekondigd Leer de lente natuurlijk, gericht op de basisprincipes van Spring 5 en Spring Boot 2:

>> BEKIJK DE CURSUS

1. Overzicht

Documentatie is een essentieel onderdeel van het bouwen van REST API's. In deze tutorial kijken we naar SpringDoc - een tool die het genereren en onderhouden van API-documenten vereenvoudigt, gebaseerd op de OpenAPI 3-specificatie, voor Spring Boot 1.x- en 2.x-applicaties.

2. Opzetten springdoc-openapi

Om springdoc-openapi automatisch de OpenAPI 3 specificatiedocumenten voor onze API te laten genereren, voegen we simpelweg de springdoc-openapi-ui afhankelijkheid van onze pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

Als we dan onze applicatie draaien, zijn de OpenAPI-beschrijvingen beschikbaar op het pad / v3 / api-docs standaard - bijvoorbeeld:

// localhost: 8080 / v3 / api-docs /

Om een ​​aangepast pad te gebruiken, kunnen we aangeven in het application.properties het dossier:

springdoc.api-docs.path = / api-docs

Nu hebben we toegang tot de documenten op:

// localhost: 8080 / api-docs /

De OpenAPI-definities zijn in JSONformaat standaard. Voor yaml formaat, kunnen we de definities vinden op:

//localhost:8080/api-docs.yaml

3. Springdoc-openapi instellen met Swagger UI

Naast het genereren van de OpenAPI 3-specificatie zelf, kunnen we springdoc-openapi integreren met Swagger UI zodat we kunnen communiceren met onze API-specificatie en de endpoints kunnen oefenen.

3.1. Afhankelijkheid van Maven

Het enige wat we hoeven te doen om springdoc-openapi in te stellen met Swagger UI is om de afhankelijkheid toe te voegen springdoc-openapi-ui naar het project pom.xml:

 org.springdoc springdoc-openapi-ui 1.5.2 

We hebben nu toegang tot de API-documentatie op:

//localhost:8080/swagger-ui.html

3.2. Ondersteuning voor branie-ui Eigendommen

Springdoc-openapi ondersteunt ook swagger-ui-eigenschappen. Deze kunnen worden gebruikt als Spring Boot-eigenschappen, met het voorvoegsel springdoc.swagger-ui.

Laten we bijvoorbeeld het pad van onze API-documentatie aanpassen. We kunnen dit doen door onze application.properties om op te nemen:

springdoc.swagger-ui.path = / swagger-ui-custom.html

Dus nu is onze API-documentatie beschikbaar op //localhost:8080/swagger-ui-custom.html.

Als een ander voorbeeld, om de API-paden op volgorde van hun HTTP-methoden te sorteren, kunnen we toevoegen:

springdoc.swagger-ui.operationsSorter = methode

3.3. Voorbeeld-API

Stel dat onze applicatie een controller heeft om te beheren Boeks:

@RestController @RequestMapping ("/ api / book") openbare klasse BookController {@Autowired privé BookRepository-repository; @GetMapping ("/ {id}") openbaar boek findById (@PathVariable lange id) {retourneer repository.findById (id) .orElseThrow (() -> nieuwe BookNotFoundException ()); } @GetMapping ("/") openbare verzameling findBooks () {retourneer repository.getBooks (); } @PutMapping ("/ {id}") @ResponseStatus (HttpStatus.OK) public Book updateBook (@PathVariable ("id") final String id, @RequestBody final Book book) {return book; }} 

Als we onze applicatie vervolgens uitvoeren, kunnen we de documentatie bekijken op:

//localhost:8080/swagger-ui-custom.html

Laten we verder kijken naar het / api / book eindpunt en bekijk de details voor het verzoek en antwoord:

4. Springdoc-openapi integreren met Spring WebFlux

We kunnen springdoc-openapi en Swagger UI integreren in een Spring WebFlux-project door springdoc-openapi-webflux-ui:

 org.springdoc springdoc-openapi-webflux-ui 1.5.2 

En, zoals eerder, zijn de documenten toegankelijk op:

//localhost:8080/swagger-ui.html

Om het pad aan te passen, kunnen we hier opnieuw de springdoc.swagger-ui.path eigendom in ons application.properties.

5. Informatie over paginering vrijgeven

Spring Data JPA integreert vrij naadloos met Spring MVC. Een voorbeeld van dergelijke integraties is Pageable ondersteuning:

@GetMapping ("/ filter") openbare pagina filterBooks (pageable pageable) {return repository.getBooks (pageable); }

In eerste instantie mogen we verwachten dat SpringDoc toevoegt bladzijde, grootte, en soort queryparameters naar de gegenereerde documentatie. Standaard voldoet SpringDoc echter niet aan deze verwachting. Om deze functie te ontgrendelen, moeten we de springdoc-openapi-data-rest afhankelijkheid:

 org.springdoc springdoc-openapi-data-rest 1.5.2 

Nu voegt het de verwachte queryparameters toe aan de documentatie:

6. Springdoc-openapi Maven Plugin gebruiken

De springdoc-openapi-bibliotheek biedt een Maven-plug-in springdoc-openapi-maven-plugin voor het genereren van OpenAPI-beschrijvingen in json en yaml formaten.

De springdoc-openapi-maven-plugin plug-in werkt met de spring-boot-maven inpluggen. Maven runt het openapi plug-in tijdens de integratietest fase.

Laten we eens kijken hoe we de plug-in in onze pom.xml:

 org.springframework.boot spring-boot-maven-plugin 2.3.3.RELEASE pre-integratie-test start post-integratie-test stop org.springdoc springdoc-openapi-maven-plugin 0.2 integratie-test genereren 

We kunnen de plug-in ook configureren om aangepaste waarden te gebruiken:

  ......... // localhost: 8080 / v3 / api-docs openapi.json $ {project.build.directory} 

Laten we de parameters die we voor de plug-in kunnen configureren eens nader bekijken:

  • apiDocsUrl - URL waar de documenten kunnen worden geopend in JSON-indeling, met een standaardwaarde van // localhost: 8080 / v3 / api-docs
  • outputFileName - Naam van het bestand waarin de definities zijn opgeslagen, standaard ingesteld op openapi.json
  • outputDir - Absoluut pad voor de map waarin de documenten zijn opgeslagen - standaard, $ {project.build.directory}

7. Automatische documentgeneratie met JSR-303 Bean-validatie

Wanneer ons model JSR-303 bean-validatie-annotaties bevat, zoals @Niet nul, @RTLnieuws, @Grootte, @Min, en @Maxgebruikt de springdoc-openapi-bibliotheek ze om aanvullende schemadocumentatie te genereren voor de overeenkomstige beperkingen.

Laten we een voorbeeld bekijken met onze Boek Boon:

public class Book {privé lange id; @NotBlank @Size (min = 0, max = 20) private String-titel; @NotBlank @Size (min = 0, max = 30) private String-auteur; }

Nu is de documentatie gegenereerd voor het Boek boon is iets informatiever:

8. Genereer documentatie met @ControllerAdvice en @ResponseStatus

Gebruik makend van @ResponseStatus op methoden in een @RestControllerAdvice class genereert automatisch documentatie voor de responscodes. In deze @RestControllerAdvice class, zijn de twee methoden geannoteerd met @ResponseStatus:

@RestControllerAdvice openbare klasse GlobalControllerExceptionHandler {@ExceptionHandler (ConversionFailedException.class) @ResponseStatus (HttpStatus.BAD_REQUEST) openbare ResponseEntity handleConnversion (RuntimeException ex) {retourneer nieuwe ResponseEntity (ex.getMessage (), HttREpStatus (); HttREpStatus (); } @ExceptionHandler (BookNotFoundException.class) @ResponseStatus (HttpStatus.NOT_FOUND) openbare ResponseEntity handleBookNotFound (RuntimeException ex) {retourneer nieuwe ResponseEntity (ex.getMessage (), HttpStatus.NOT_FOUND); }}

Als gevolg hiervan kunnen we nu de documentatie voor de responscodes 400 en 404 bekijken:

9. Genereer documentatie met @Operatie en @ApiResponses

Laten we vervolgens kijken hoe we een beschrijving aan onze API kunnen toevoegen met behulp van een aantal OpenAPI-specifieke annotaties.

Om dat te doen, zullen we het / api / boek / {id} eindpunt met @Operatie en @ApiResponses:

@Operation (summary = "Haal een boek op met zijn id") @ApiResponses (waarde = {@ApiRespons (responseCode = "200", description = "Found the book", content = {@Content (mediaType = "application / json" , schema = @Schema (implementatie = Book.class))}), @ApiResponse (responseCode = "400", description = "Ongeldige id opgegeven", content = @Content), @ApiResponse (responseCode = "404", description = "Boek niet gevonden", content = @Content)}) @GetMapping ("/ {id}") openbaar boek findById (@Parameter (beschrijving = "id van te doorzoeken boek") @PathVariable lange id) {retourneer opslagplaats. findById (id) .orElseThrow (() -> nieuwe BookNotFoundException ()); }

En hier is het effect:

Zoals we kunnen zien, is de tekst die we hebben toegevoegd @Operatie wordt op het API-bewerkingsniveau geplaatst. Evenzo is de beschrijving toegevoegd aan verschillende @ApiResponse elementen in de @ApiResponses containerannotatie is hier ook zichtbaar, wat betekenis toevoegt aan onze API-reacties.

Blijkbaar krijgen we geen schema voor de antwoorden 400 en 404 hierboven. Omdat we een leegte hebben gedefinieerd @Inhoud voor hen worden alleen hun beschrijvingen weergegeven.

10. Kotlin-ondersteuning

Aangezien Spring Boot 2.x eersteklas ondersteuning biedt voor Kotlin, ondersteunt SpringDoc deze JVM-taal standaard voor Boot 2.x-toepassingen.

Om dit in actie te zien, maken we een eenvoudig Foo API in Kotlin.

Na de eerste installatie voegen we een dataklasse en een controller toe. We voegen ze toe aan een subpakket van onze Boot-app, zodat wanneer deze wordt uitgevoerd, het onze FooController samen met de eerdere BookController:

@Entity data class Foo (@Id val id: Long = 0, @NotBlank @Size (min = 0, max = 50) val name: String = "") @RestController @RequestMapping ("/") class FooController () { val fooList: List = listOf (Foo (1, "one"), Foo (2, "two")) @Operation (summary = "Get all foos") @ApiResponses (value = [ApiResponse (responseCode = "200", description = "Found Foos", content = [(Content (mediaType = "application / json", array = (ArraySchema (schema = Schema (implementatie = Foo :: class)))))]), ApiResponse (responseCode = "400 ", description =" Slecht verzoek ", content = [Content ()]), ApiResponse (responseCode =" 404 ", description =" Geen Foos gevonden ", content = [Content ()])]) @GetMapping (" / foo ") fun getAllFoos (): List = fooList}

Als we nu op onze API-documentatie-URL klikken, zien we het Foo API ook:

Om de ondersteuning van Kotlin-typen te verbeteren, kunnen we deze afhankelijkheid toevoegen:

 org.springdoc springdoc-openapi-kotlin

Daarna ziet ons Foo-schema er informatiever uit. Vergelijkbaar met toen we JSR-303 Bean Validation hadden toegevoegd:

11. Conclusie

In dit artikel hebben we geleerd om springdoc-openapi op te zetten in onze projecten. Vervolgens hebben we gezien hoe we springdoc-openapi kunnen integreren met de Swagger UI. We hebben ook gezien hoe we dit konden doen met Spring Webflux-projecten.

Vervolgens hebben we de springdoc-openapi Maven-plug-in gebruikt om OpenAPI-definities voor onze API's te genereren, en we hebben gezien hoe we paging- en sorteerinformatie uit Spring Data kunnen vrijgeven. Daarna hebben we gekeken hoe springdoc-openapi automatisch documentatie genereert met behulp van JSR 303 bean-validatieannotaties en de @ResponseStatus annotaties in @ControllerAdvice klasse.

Vervolgens leerden we hoe we een beschrijving aan onze API konden toevoegen met behulp van een paar OpenAPI-specifieke annotaties. Ten slotte hebben we een kijkje genomen bij OpenAPI's ondersteuning van Kotlin.

De springdoc-openapi genereert API-documentatie volgens de OpenAPI 3-specificatie. Bovendien verwerkt het ook de Swagger UI-configuratie voor ons, waardoor het genereren van API-documenten een vrij eenvoudige taak is.

Zoals altijd is de code beschikbaar op GitHub.

REST onder

Ik heb zojuist het nieuwe aangekondigd Leer de lente natuurlijk, gericht op de basisprincipes van Spring 5 en Spring Boot 2:

>> BEKIJK DE CURSUS