Swagger: Das REST API Documentation Tool

Bei der Softwareentwicklung spielt eine gute Dokumentation immer eine wichtige Rolle und erleichtert dem Entwickler maßgeblich die Arbeit und den Umgang mit dem zu entwickelnden Projekt.

Gerade die Dokumentation der API ist hier von besonderer Bedeutung, da in vielen tausenden Zeilen Code häufig der Überblick über die einzelnen Funktionen der Schnittstelle verloren geht.  

Was ist Swagger?

Swagger ist ein auf OpenAPI basierendes Open-Source-Framework, welches die Dokumentation von REST APIs vereinfachen soll und mit Hilfe der Swagger UI, diese direkt als interaktive API Dokumentation rendert. 

Java Implementierung

Um Swagger erfolgreich in einem Java Spring Boot Projekt zu implementieren, muss zuerst die pom.xml angepasst werden.  Hier werden zwei weitere Dependencies benötigt, um die Springfox Implementation zu ermöglichen und die Swagger UI nutzen zu können. 

<dependency> 
   <groupId>io.springfox</groupId> 
   <artifactId>springfox-swagger2</artifactId> 
   <version>2.9.2</version> 
</dependency> 
<dependency> 
   <groupId>io.springfox</groupId> 
   <artifactId>springfox-swagger-ui</artifactId> 
   <version>2.9.2</version> 
</dependency> 

Nun muss nur noch die SpringFoxConfig Klasse erstellt werden und die Implementierung ist vollständig. 

Durch die @EnableSwagger2 Annotation wird Swagger aktiviert. 

@Configuration 
@EnableSwagger2 
@Import(BeanValidatorPluginsConfiguration.class) 
public class SpringFoxConfig { 
 
    @Bean 
    public Docket api(){ 
        return new Docket(DocumentationType.SWAGGER_2).select() 
                .apis(RequestHandlerSelectors.any()) 
                .paths(PathSelectors.any()).build(); 
    } 
} 

Nun kann man sich unter http://localhost:8080/your-app-root/swagger-ui.html die generierte HTML Seite anzeigen lassen.

C# Implementierung

Die Implementierung in einem C# Projekt ist nahezu genauso simpel, wie in einem Java Spring Boot Projekt. 

Hierfür muss zuerst Swashbuckle hinzugefügt werden, dazu wird mit der Paket-Manager-Konsole im Verzeichnis der TodoApi.csproj-Datei das Paket Swashbuckle.AspNetCore -Version 5.0.0 installiert. 

Daraufhin muss die Startup-Klasse angepasst werden für die Verwendung von OpenApi: 

using Microsoft.OpenApi.Models;

services.AddSwaggerGen(c => 
{ 
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyProject Api", Version = "v1" }); 
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; 
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 
    c.IncludeXmlComments(xmlPath); 
}); 

Zum Abschließen der Implementierung wird jetzt noch die Startup.Configure-Methode angepasst, um die SwaggerUI zu generieren: 

app.UseSwagger(); 
app.UseSwaggerUI(c => 
{ 
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "MyProject Api"); 
}); 

Zusätzlich können nun noch in der TodoApi.csproj-Datei Warnungen für XML-Kommentare deaktiviert werden, da mit Hilfe dieser die Dokumentation in C# erfolgt:  

<PropertyGroup> 
  <GenerateDocumentationFile>true</GenerateDocumentationFile> 
  <NoWarn>$(NoWarn);1591</NoWarn> 
</PropertyGroup> 

Nun kann auch hier die SwaggerUI unter dem generierten Endpunkt im Browser gestartet werden. 

Dokumentation

Die SwaggerUI ist fertig generiert und jetzt beginnt die eigentliche Dokumentation, indem die einzelnen API Methoden und ihre Parameter mit Hilfe der OpenApi beschrieben werden. 

In Java funktioniert dies durch verschiedene Annotationen: 

@GetMapping("api/Aufgabe/{prozessid}") 
@ApiOperation(value = "Gibt alle Aufgaben eines Prozesses zurueck") 
@ApiImplicitParams({ 
        @ApiImplicitParam(name = "prozessid", value = "spezifische ID eines Prozesses", required = true, dataType = "int", paramType = "query") 
}) 
public ResponseEntity<Aufgaben> getAlleAufgaben(@PathVariable int prozessid) { 
 
    List<Aufgaben> aufgaben = aufgabenHandler.getAufgaben(prozessid); 
    return new ResponseEntity<Aufgaben>(aufgaben, HttpStatus.OK); 
 
} 

In C# funktioniert dies durch Verwendung von XML-Kommentaren: 

/// <summary> 
/// Gibt alle Aufgaben eines Prozesses zurueck 
/// </summary> 
/// <param name="prozessid">spezifische ID eines Prozesses</param> 
/// <returns></returns> 
[Route("{prozessid}")] 
[HttpGet] 
public async Task<AufgabeWrapper> GetAlleAufgaben(int prozessid) 
{ 
    List<Aufgabe> aufgaben = await aufgabeHandler.GetAufgaben(prozessid); 
    return new AufgabeWrapper {aufgaben = aufgaben}; 
}

Daraus generiert Swagger die fertig dokumentierte Methode: 

So kann nun jede Methode der API dokumentiert werden und am Ende entsteht eine sehr übersichtliche und visuell dargestellte Dokumentation die sowohl für Entwickler, als auch für den Kunden eine Hilfestellung bietet. 

Darüber hinaus ist es möglich die SwaggerUI mit Postman zu öffnen, was es ermöglicht Methoden direkt zu testen und Aufrufe durchzuführen.