02.07.2016
Spring Boot - Dokumentation mit Swagger
In diesem Artikel wird gezeigt, wie man REST-Schnittstellen, die mit SpringBoot erstellt wurden mit Swagger dokumentiert und gezeigt, welche Annotationen dafür von Swagger zur Verfügung bestellt werden. Auß:erdem wird gezeigt, wie sich die die REST-API direkt aus der Dokumentation heraus testen läßt. Zusätzlich werden Alternativen zu Swagger genannt.
In der Maven-Datei pom.xml
folgende Dependencies ergänzen:
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.5.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.5.0</version> </dependency>
In der Hauptklasse Application
die Annotation @EnableSwagger2
hinzufügen.
package org.hameister; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import springfox.documentation.swagger2.annotations.EnableSwagger2; @SpringBootApplication @EnableSwagger2 public class Application { public static void main( String[] args ) throws Exception { SpringApplication.run(Application.class, args); System.out.println( "SpringBoot started!" ); }
Wenn man die Applikation startet, dann ist ein erstes Gerüst unter der URL http://localhost:8080/swagger-ui.html zu erreichen.

Im folgenden Codeschnipsel wurde die Methode getPersons()
um eine Dokumention erweitert. mit @ApiOperation
wird die Methode beschrieben. Mit den Annotationen @ApiResponses
und @ApiResponse
werden Error-Codes beschrieben.
Die übrigen Annotationen sind in der Dokumentation von Swagger zu finden.Core-Annotationen beschrieben.
@RequestMapping(value = "/api/persons", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE) @ApiOperation(value = "", notes = "Returns a collection with all Persons from the database.", response = Person.class, responseContainer = "Collection") @ApiResponses(value = { @ApiResponse(code = 200, message = "Response contains a Collection with Persons"), @ApiResponse(code = 400, message = "Bad Request") }) ResponseEntity<Collection<Person>> getPersons() { Collection<Person> persons = personService.findAll(); return new ResponseEntity<Collection<Person>>(persons, HttpStatus.OK); }
Vorteil von der Swagger-Dokumentation ist, dass man die API direkt aus der Dokumentation heraus testen kann.

In dem Beispiel wird als id
die 1
angegeben. Bei einer POST-Operation kann auch JSON verwendet werden.
Ein Nachteil von Swagger ist, dass der Service nach jeder kleinen Änderung neu gestartet werden muss, wodurch dass Dokumentieren nicht besonders schnell geht. Eine weitere Unschönheit ist, dass die Annotationen den Quellcode schlechter lesbar machen. Altenativen zu Swagger sind Spring REST Docs und LazyDoc.