Wollten Sie schon immer eine Dokumentation für Ihre Express-API haben, die auf Anmerkungen basiert? Ich habe Und leider haben wir keine Möglichkeit gefunden, ohne manuell eine swagger.json Datei zu erstellen. So einfach war mein Wunsch: Ich möchte eine saubere Express-App mit mehreren Endpunkten haben und möchte für jeden Endpunkt, der sich in der Nähe der Endpunktimplementierung befindet, eine umfassende Dokumentation, nicht in einer separaten Datei.

Vielleicht fehlen mir nur einige Google-Kenntnisse, aber ich entschied, dass es für mich viel einfacher sein würde, ein solches Tool zu erstellen. Und hier ist es: Man-Swagger-Express

Erste Schritte

Beispiel hier wird in TypeScript geschrieben, aber das gleiche kann in Javascript-Projekt gemacht werden.
Stellen Sie sich also eine klassische Express-App vor:

Hier haben wir eine Ressource "Buch" und einige grundlegende CRUD-Endpunkte. Die Frage lautet: „Wie würden Sie dieser API eine coole Swagger-Dokumentation hinzufügen?“ Ich wollte dies unbedingt mithilfe von Anmerkungen tun, um jede Endpunktdokumentation nah am Endpunkt selbst zu halten.

Das können Sie mit mgr-swagger-express machen :
index.ts :

BookService.ts :

Es gibt einen Bot mehr Code, aber jetzt liegt die gesamte Dokumentation in der Nähe des Endpunkts.
Mal sehen, was hier passiert:

• In der Indexdatei erstellen wir wie gewohnt eine Express-App. Außerdem müssen wir alle Middlewares initialisieren (wobei der bodyParser der wichtigste ist).
• Danach rufen wir SET_EXPRESS_APP auf, um das App-Objekt global zu setzen. Auf diese Weise kann mgr-swagger-express Handler an Endpunkte anschließen
• Erst danach können wir den Service mit Anmerkungen importieren. Es muss keine Klasse sein, es können nur Funktionen sein.
• Dann erstellen wir eine Instanz unseres Dienstes (oder rufen eine Init-Funktion auf, wenn wir keine Klassen verwenden)
• Und wir generieren die Swagger-Konfiguration basierend auf allen im Projekt vorhandenen Anmerkungen und hängen sie mit dem Swagger-UI-Express-Paket an unsere App an

Innerhalb des Dienstes sind mehrere Dinge im Gange, aber lassen Sie uns nur auf einige davon eingehen. Alles andere, was Sie im mg-swagger-express-Repo leicht finden können:

• Im Konstruktor rufen wir die Funktion addSwaggerDefinition . Es registriert ein Swagger-Modell mit einem bestimmten Namen. In unserem Fall definieren wir BookDefinition unter einem BookDefinition um danach mit #/definitions/Book darauf zu verweisen
• Alle Handler sind mit @GET @POST @PUT @DELETE Befehlen versehen. Alle von ihnen nehmen Argumente eines Objekts vom Typ SwaggerEndpoint :
  

   path: string; auth?: string; description?: string; tags?: string[]; parameters?: SwaggerURLParameter[]; query?: SwaggerQueryParameter; body?: SwaggerBodyParameter; success?: SwaggerSuccessResponse; 

  
  

  Es handelt sich im Grunde genommen um das klassische Objekt zur Definition von Swagger-Endpunkten, nichts Besonderes, außer dem Authentifizierungsfeld, aber ich werde in Zukunft darauf zurückkommen

  
  Alle Handler sollten die folgende Unterschrift haben:
  

   (args: object, context: Context) => Promise<any> 

  
  

  Das args-Objekt enthält alle Parameter, die zu Ihrem Endpunkt geleitet werden. book_id können URL-Parameter (wie in unserem Beispiel book_id ), Abfrageparameter oder sogar der book_id .

  
  
  

  Das Kontextobjekt wird für die Authentifizierung und Sicherheit verwendet, aber später noch einmal.

  
  

  Fazit

  
  

  Jetzt haben wir eine einfache CRUD-Express-API, die mit Swagger kommentiert ist, und eine schöne Swagger-Benutzeroberfläche, in der alle Swagger-Definitionen in der Nähe der Endpunktimplementierung liegen. Wie immer - immer froh über Feedback! ️