Das Dokument behandelt die Verwendung von Swagger für REST-API-Dokumentation und Code-Generierung in Java-Anwendungen. Es beschreibt die Integration von Swagger-Core mit JAX-RS, die Nutzung von Annotationen zur Schnittstellendefinition und die Erstellung von OpenAPI-Dateien durch Maven-Plugins. Zusätzlich werden verschiedene Tools wie Swagger-UI, Swagger-Editor und Swagger-Codegen vorgestellt, die die Entwicklung und Interaktion mit APIs unterstützen.

1. Swagger – REST APIs im Griff
Expertenkreis Java, 21.06.2018, GEDOPLAN
Dominik Mathmann, GEDOPLAN GmbH

2. Swagger?
The World's Most Popular API Tooling
https://swagger.io/
by SmartBear
Toolset für REST-Webservice
Dokumentation
Code Generierung
Testen
2
gedoplan.
de

3. 3
gedoplan.
de

4. 4
gedoplan.
de
OpenAPI
json/yaml

5. Die Idee
5
gedoplan.
de
.java
Bottom-up
Top-down
OpenAPI
json/yaml
OpenAPI
json/yaml
Doc
Client
Server
Doc
Client

6. Core-Tools
6
gedoplan.
de
swagger-core
Integration in Java Anwendungen
swagger-ui
Visualisierung und Interaktion
swagger-editor
Design und Interaktion
swagger-codegen
Generierung von Clients

7. swagger-core, JAX-RS
7
gedoplan.
de
Java / JAX-RS Integration für Swagger
Verwendung von Annotationen
zur Definition der Schnittstellen
zur Dokumentation
Generierung von Open API Files
per JAX-RS Resource
per Maven Plugin
Bottom-Up Vorgehen

8. swagger-core, JAX-RS
8
gedoplan.
de
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jaxrs</artifactId>
<version>1.5.18</version>
</dependency>
@ApplicationPath("/webresources")
public class ApplicationConfig extends Application {
public ApplicationConfig() {
BeanConfig beanConfig = new BeanConfig();
beanConfig.setVersion("1.0.0");
beanConfig.setTitle("Expertenkreis Demo");
beanConfig.setHost("localhost:8080");
beanConfig.setBasePath("/ek-swagger-1.0-SNAPSHOT/webresources");
beanConfig.setResourcePackage("de.gedoplan.ek.swagger.resource");
beanConfig.setScan(true);
}

9. swagger-core, Annotations
9
gedoplan.
de
@Api , Swagger Resource markieren
@ApiOperation, Funktionsbeschreibung
@ApiParam, Parameterbeschreibung
@ApiResponse, Return Beschreibung
…

10. Alternativ: swagger-maven-plugin
10
gedoplan.
de
Generierung Open API File über Maven Plugin
Konfigurierbar
Ressource-Pfad
Projektinformationen
Ausgabeformat
automatische Weiterverarbeitung möglich
z.B. zur Code-Generierung
<groupId>com.github.kongchen</groupId>
<artifactId>swagger-maven-plugin</artifactId>

11. swagger-ui
11
gedoplan.
de
Web-Anwendung
als Online-Version
als Download zum selber hosten
grafische Aufbereitung der API
Interaktion mit der API

12. swagger-ui
12
gedoplan.
de

13. swagger-editor
13
gedoplan.
de
Web-Editor zum Beschreiben Erstellen von Open API Files
Web-Anwendung
als Online-Version
als Download zum selber hosten
Top-Down Vorgehen

14. swagger-editor
14
gedoplan.
de

15. swagger-codegen
15
gedoplan.
de
Generierung von Clients
Anwendung integriert in swagger-editor
über Java CLI
java -jar swagger-codegen-cli-2.3.1.jar
generate -i swagger.json -l typescript-angular

16. swagger-codegen
16
gedoplan.
de
Client

17. swagger-codegen
17
gedoplan.
de
Server

18. swagger-codegen, typescript-angular
18
gedoplan.
de
public class ContactPerson {
private Integer id;
private String firstname;
private String lastname;
private String mail;
export interface ContactPerson {
id?: number;
firstname?: string;
lastname?: string;
mail?: string;
@Path("cperson")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ContactPersonResource {
@GET
public List<ContactPerson>
getContactPersons() {...}
@Injectable()
export class ContactPersonService {
public getContactPersons(…) :
Observable<Array<ContactPerson>> {
…
return
this.httpClient.get
(`${this.basePath}/cperson`);
}

19. Individualisierung
19
gedoplan.
de
Java > Open API
@SwaggerDefinition, @Extension
ReaderListener
Open API > codegen
Code-Template Anpassung (mustache.js)
Anpassung Java-Anwendung (OpenSource)

20. Go Swagger?
20
gedoplan.
de
Pro
geringer Einführungsaufwand
enge Bindung zwischen Dokumentation und Code
umfassendes Tooling (Auswertung, Testen)
Generierung von Code
Contra
enge Bindung an Open API / Tooling
Beschränkungen durch Generatoren
ggf. Anpassung der API Generierung
ggf. unzureichende Implementierung von Clients

21. Demo
21
gedoplan.
de
GEDOPLAN, Expertenkreis Java
https://gedoplan-it-consulting.de/expertenkreis-java/
Demos
https://github.com/GEDOPLAN/expertenkreis-swagger