Sicherlich traten während der Entwicklung der API mehrmals Schwierigkeiten mit der Dokumentation auf: Entweder existiert sie nicht, dann zeigt sie das im Code beschriebene Verhalten nicht an.
Aus Sicht des Entwicklers dauert das Schreiben von Dokumentation (nur intern) nicht weniger als das Schreiben des Codes selbst. Ist das bekannt Dann willkommen bei cat.
Gibt es ein Problem?
Unser Team hat die API schon lange entwickelt, die die Grundlage unseres Produkts bildet. Zu diesem Zeitpunkt gab es jedoch keine Live-Benutzer, sodass niemand die Notwendigkeit sah, etwas für den externen Gebrauch zu dokumentieren. Wie alle Teams haben wir mit der internen Dokumentation begonnen - zuerst eine Methode, dann eine andere. In unserem Bereich in Confluence finden Sie ein Dutzend anderer Seiten, auf denen hübsche Informationen angezeigt werden - welche Art von API-Methode, welchen Abfragepfad sie hat, welche Parameter und was wir in der Ausgabe erhalten.
Alles wäre in Ordnung, aber der Code ändert sich ständig und wächst, die Geschäftsanforderungen ändern sich. Zusammen mit Codeänderungen können sich APIs ändern, was zwangsläufig zu Änderungen auf diesen Seiten führt. Nun, wenn es eine Seite ist und nur 1 Mal. Und wenn es weitere Änderungen gibt?
Wir haben so viel wie möglich eine Lösung (unser eigenes Fahrrad) gefunden, während wir uns an den üblichen Aktivitäten des Entwicklers beteiligten, um nicht daran zu denken, interne Dokumentationen zu schreiben und zu aktualisieren.
Einige Lösungen
Es gibt verschiedene Möglichkeiten, wie der Code und seine Spezifikation miteinander verbunden werden können, aber für mich selbst unterscheide ich zwei:
- Code zuerst, Spezifikation als nächstes
- Spezifikation zuerst, Code als nächstes
Ich beginne mit der zweiten, wie mit der Option, die für uns am wenigsten geeignet war.
Spezifikation zuerst, Code als nächstes befasst sich mit der Codegenerierung, basierend auf der Spezifikation, dh der Code existiert erst, wenn Sie die Spezifikation schreiben.
Das einfachste Beispiel ist Swagger Codegen.
Unser Unternehmen hat Teams, die diesen Ansatz in ihrem Produkt verwenden, aber in unserem Fall war er nicht sehr geeignet. Zu der Zeit, als wir mit einem Bedarf konfrontiert waren, hatten wir bereits viele API-Methoden geschrieben. Aus Gründen der Dokumentation wollten wir die Entwicklungsprozesse nicht radikal ändern - zuerst schreiben wir Entwürfe, dann codieren wir und erst dann die Spezifikationsbeschreibung.
Code zuerst, Spezifikation als nächstes - alles ist einfach, zuerst schreiben wir den Code, dann die Spezifikation. Aber dann stellte sich die Frage - und ob wir keine unnötigen Bewegungen machen wollen, damit die Spezifikation generiert wird?
Eine Reihe von Anwendungen in unserem Unternehmen verwenden diesen Ansatz, der jedoch nicht besonders automatisiert ist. Die API-Methoden werden mit allen Arten von Anmerkungen gewichtet, auf deren Grundlage die Spezifikation erstellt wurde. Dieselben Anmerkungen entsprechen jedoch häufig nicht der Realität, da die Anforderungen und Funktionen der Anwendung wachsen und sich ändern.
"Sie sind ein Programmierer", sagte ich mir und beschloss, einen kleinen Prototyp zu schreiben, der es mir ermöglichen würde, nicht all diesen Routine-Müll zu schreiben.
Als ich die nächste Aufgabe erledigte und den n-ten Funktionstest schrieb, stellte ich fest, dass wir bereits alle Informationen für die Spezifikation haben.
Wir haben Funktionstests, die fast alle Informationen enthalten, die wir benötigen:
- Was heißt
- Was heißt (Parameter, Körper, Überschriften usw.)
- Welches Ergebnis wird erwartet (Statuscode, Antworttext)
Warum nicht dein eigenes Fahrrad bauen?
Fast alles, was wir normalerweise in den Spezifikationen schreiben, die wir haben. Der Fall für Small-Code in diesem Fall.
Da unsere Bewerbung in PHP ist, kam mir die Reflexion zu Hilfe. Mit ein wenig Magie der Reflexion sammeln wir alle uns zur Verfügung stehenden API-Methoden, entnehmen Daten aus Funktionstests, extrahieren Daten über die Autorisierung und deren Typ. Von den üblichen Anmerkungen zu den Methoden erhalten wir die Beschreibung der Methode selbst. Nachdem wir all dies gemischt und mit spezifischen Funktionen für das in unseren Lösungen verwendete Framework gewürzt haben, erhalten wir in ein paar Wochen eine Lösung, die vom Entwickler praktisch keine zusätzliche Zeit benötigt.
Das Generieren einer Spezifikation ist nur der erste Schritt. Sie benötigen eine Dokumentation aus der Spezifikation, die von einem externen Entwickler bereitgestellt werden kann. Eine der Anforderungen für die Dokumentation ist, dass sie in mehreren Sprachen dargestellt werden sollte. Derzeit erstellen wir jedoch nur eine Dokumentation in englischer Sprache. Bisher genug, aber es wird notwendig sein, einen Mechanismus zum Empfangen von Übertragungen an unser Spezifikationsgenerierungsschema anzuschließen.
Das Problem, das wir ursprünglich gelöst hatten. Mit dieser Lösung sind jedoch viele Risiken verbunden:
- Preisunterstützung für Ihr eigenes Fahrrad
- Erweiterung der notwendigen Funktionalität
- Aktualisierung und Synchronisierung von Übersetzungen
Diese Risiken müssen berücksichtigt werden, und wenn sie zu wirken beginnen, müssen Maßnahmen ergriffen werden.