Springfox Swagger mit externem Markdown erweitern

Dokumentationen von REST APIs sind für deren Anwender essentiell. Ohne eine ansprechende und verständliche Dokumentation lässt sich eine solche API bestenfalls nach dem „trial and error“-Prinzip anwenden. Mit Swagger wurde eine Spezifikation geschaffen, die API-Dokumentationen im JSON- oder YAML-Format vorgibt. Springfox baut auf dieser Spezifikation auf und bietet, beispielsweise per Annotationen, die Möglichkeit in Spring-Projekten die Dokumentation direkt innerhalb des REST Controllers zu hinterlegen. Über den automatisch erzeugten /api-docs Endpunkt wird eine swagger konforme, generierte API-Dokumentation zur Verfügung gestellt. In diesem Artikel möchte ich eine Möglichkeit zeigen wie man diese Dokumentation durch das Inkludieren externer Markdown-Dateien erweitern kann.

Swagger und Springfox

Swagger ist ein Open-Source-Framework das unter anderem Hilfsmittel zur Dokumentation von REST APIs zur Verfügung stellt. Neben einer Spezifikation für eine JSON-basierte API-Dokumentation werden Tools und Frameworks zum Erzeugen dieser Dokumentation angeboten. Diese JSON Representation kann beispielsweise mit Hilfe von Swagger-UI im Browser visualisiert werden. Springfox ist eine Spring-Implementierung der Swagger-Spezifikation. Springfox bietet anhand von Annotationen die Möglichkeit API-Dokumentationen automatisch zu generieren und anhand des /api-docs Endpoints bereitzustellen.

Motivation

Ein Ziel von Springfox ist die Zentralisierung und Versionierung der Dokumentation, sowie die automatische Bereitstellung. Werden die Beschreibungen der REST-Endpunkte allerdings zu ausführlich, so dass die entsprechenden Java-Klassen zum Großteil aus API-Dokumentation bestehen, sollte man das Konzept der „Dokumentation im Code“ zumindest hinterfragen. Eine Alternative zur Generierung der Dokumentation wäre beispielsweise das Bereitstellen einer statischen JSON-Dokumentation über einen definierten REST-Endpunkt. Eine solche statische Dokumentation lässt sich über den Swagger-Editor erzeugen. Die erzeugte Datei lässt sich ebenfalls versionieren, ist allerdings schwieriger zu lesen und es besteht im Code keine direkte sichtbare Beziehung zu den entsprechenden Endpunkten. Um diese Nachteile zu umgehen zeige ich im folgenden eine Möglichkeit der Verknüpfung von Markdown-Ressourcen mit den jeweiligen API-Dokumentationen. Sowohl Swagger-UI als auch der Swagger-Editor unterstützen Markdown innerhalb der Endpunktbeschreibungen.

Springfox Lifecycle

Springfox parsed die Swagger-Dokumentation nachdem der Spring Context aufgebaut wurde. Intern nutzt Springfox hierfür das Spring-Plugin-Projekt . Mit Spring Plugin lassen sich Interfaces registrieren deren Implementierungen automatisch in PluginRegistries gesammelt werden. Springfox definiert unter anderem die OperationBuilderPluginRegistry mit Implementierungen des OperationBuilderPlugin-Interfaces. Eine Implementierung dieses Interfaces ist der OperationNotesReader der Springfox-Annotationen auswertet und die Beschreibung eines REST-Endpunktes erzeugt. Springfox implementiert für jede Swagger Annotation eine Reader-Klasse, welche die einzelnen Elemente der Swagger-Dokumentation anhand der Annotation Properties zusammenbaut. An dieser Stelle lassen sich eigene Annotationen bzw. eigene Implementierungen des OperationBuilderPlugin Interfaces anlegen, um wie im nächsten Abschnitt beschrieben externe Markdown-Dateien zu inkludieren.

Implementierung

Um eine eigene Annotation für Markdown-Dateien nutzen zu können, muss das OperationBuilderPlugin Interface implementiert werden. Eine Bean dieser Klasse wird durch die @Component Annotation beim Erzeugen des Spring Contexts angelegt. Die apply-Methode wird automatisch für alle Implementierungen dieses Interfaces vom Springfox DocumentationPluginsManager aufgerufen, so dass man sich um das Bootstrappen und Registrieren nicht selber kümmern muss.

1@Component
2@Order(SwaggerPluginSupport.SWAGGER_PLUGIN_ORDER)
3public class OperationNotesResourcesReader implements OperationBuilderPlugin {
4    private final DescriptionResolver descriptions;
5 
6    final static Logger logger = LoggerFactory.getLogger(OperationNotesResourcesReader.class);
7 
8    @Autowired
9    public OperationNotesResourcesReader(DescriptionResolver descriptions) {
10        this.descriptions = descriptions;
11    }
12 
13    @Override
14    public void apply(OperationContext context) {
15 
16        Optional<ApiNotes> methodAnnotation = context.findAnnotation(ApiNotes.class);
17        if (methodAnnotation.isPresent() && StringUtils.hasText(methodAnnotation.get().value())) {
18 
19            final String mdFile = methodAnnotation.get().value();
20            URL url = Resources.getResource(mdFile);
21            String text;
22            try {
23                text = Resources.toString(url, Charsets.UTF_8);
24            } catch (IOException e) {
25                logger.error("Error while reading markdown description file {}", mdFile, e);
26                text = "Markdown file " + mdFile + " not loaded";
27            }
28 
29            context.operationBuilder().notes(descriptions.resolve(text));
30        }
31    }
32 
33    @Override
34    public boolean supports(DocumentationType delimiter) {
35        return SwaggerPluginSupport.pluginDoesApply(delimiter);
36    }
37}

Innerhalb der apply-Methode wird hier lediglich im classpath nach der Markdown resource gesucht und diese als String geladen. Die Annotation „ApiNotes“ habe ich selber definiert. Sie erwartet als Argument den Namen der Markdown resource. An dieser Stelle könnte man beispielsweise auch Inhalte aus einem CMS oder einer Datenbank verwenden um die Dokumentation mit Inhalten zu füllen.

1@Target({ElementType.METHOD})
2@Retention(RetentionPolicy.RUNTIME)
3public @interface ApiNotes {
4    String value() default "";
5}

Ein Beispiel einer RestController Methode mit der entwickelten Annotation könnte wie folgt aussehen:

1@ApiOperation(
2            value = "Add a comment",
3            consumes = "application/json" ,
4            produces = "application/json" )
5    @ApiNotes("addComment.md")
6    @ApiResponses(value = {
7            @ApiResponse(code = 201, message = "The comment was created")})
8    @RequestMapping(value= { "/" }, method = { RequestMethod.POST })
9    public void addComment(@RequestBody(required = true) Comment comment) {
10        ...
11    }

Die hier genutzte addComment.md Markdown-Datei muss in dieser Implementierung im Classpath bzw. dem resource-Verzeichnis der Anwendung vorhanden sein. Die folgende Abbildung zeigt die Swagger Dokumentation für den oben dargestellten REST-Endpunkt addComment mit Markdown-Elementen wie Tabellen und Bildern. Für die Darstellung der Dokumentation wurde Swagger-UI verwendet.

Fazit

Swagger bietet viele Möglichkeiten seine REST-Endpunkte zu dokumentieren und bereitzustellen. In diesem Post habe ich eine Möglichkeit gezeigt, wie die Spring Implementierung von Springfox erweitert werden kann um Dokumentation aus externen Quellen – aber mit Verknüpfung zu den Endpunkten – zu benutzen.