Spring Boot Config Server und Client mit Git-Repository

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.