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
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
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>
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