Die REST API der B2B wird automatisch durch Swagger dokumentiert.
Weboberfläche
Die Doku wird durch die B2B unter folgendem Link angezeigt: http://<my-host>:<my-port>/b2bbp-engine/api/swagger-ui.html. Hierbei wird ein Login der App zur Authentifizierung benötigt.
Dev Konfiguration
Mit Hilfe von Swagger kann automatische Doku für spring-RestController generiert werden.
Die Doku wird im Code per Annotation geschrieben. Die B2B stellt die Doku dann per Weboberfläche zur Verfügung.
Swagger wird in der B2B mit der Klasse SwaggerConfiguration konfiguriert. Diese Klasse muss für das Erstellen neuer Swagger-Doku nicht weiter angepasst werden.
Dev Dokumentation am RestController
Swagger ist geeignet für RestController, also für Klassen, die mit @RestController annotiert sind.
Als Beispiel dient das org.b2bbp.rest.controller.ui.ControllerTemplate.
Die Klasse muss zusätzlich mit @Api annotiert werden, damit Swagger Doku erzeugt werden kann. Außerdem ist das Argument tags zu befüllen.
Beispiel:
@RestController
@RequestMapping(value = "/ui/admin/v1")
@Api(tags = {"internal"})
public class AdminController {...}
Ein Endpunkt (eine Methode, die z.B. mit @PostMapping annotiert ist) kann dokumentiert werden, indem die Annotation @ApiOperation an der Methode gesetzt wird. Die Dokumentation ist als Argumente (value, notes) der Annotation zu übergeben. Ggf. können weitere Argumente der Annotation genutzt werden, vgl. hierzu das Javadoc von ApiOperation.
Beispiel:
@ApiOperation(value = "trigger service execution",
notes = "The service runs on the node ...")
@PostMapping(value = "/execute")
public void executeJobNow(...) {...}
Falls der Endpunkt Parameter hat, also falls die Methode Argumente hat, die mit @RequestParam annotiert sind, dann können die Parameter zusätzlich mit @ApiParam annotiert werden. Mit Hilfe dieser Annotation können Parameter dokumentiert werden. Eine Beschreibung kann über das Argument value übergeben werden. Für die weiteren Annotations-Argumente vgl. das Javadoc von ApiParam.
Beispiel:
@ApiOperation(value = "...")
@PostMapping(value = "/execute")
public void executeJobNow(
@ApiParam(value = "ServiceId of a SchedulerRegisterService")
@RequestParam
String job) {...}