Hier eine kleine Liste der Befehle die man benötigt wenn man mit nodejs und swagger ein Projekt erstellen möchte.
Was muss auf dem Rechner vorhanden sein
npm
nodejs (ich nutze zur Zeit die Version 8.9.1)
nvm (Nur auf dem Mac. Damit man schnell zwischen den node Versionen hin und her wechseln kann)
swagger
Installation
NPM und NodeJS
Npm installiert man am besten indem man den NodeJS Installer herunterläd und installiert.
Npm ist in dem Node Installer mit integriert.
NVM !Nur auf dem Mac
Nvm könnt ihr am einfachsten über das NVM Installer Script installieren. Wie das geht seht ihr auf der Verlinkten Seit.
Swagger
Swagger kann einfach über npm installiert werden:
npm install -g swagger
Achtung Wenn nvm nicht auf dem Rechner in den Pfad eingetragen wurde, muss man bei jedem Start der Console / des Terminals die node Version wieder einstellen und gegebenen Falls swagger neu installieren.
Swagger Project erstellen
Zuerst erstellt man einen neuen Ordner für das Projekt. Ich verwende dabei immer folgendes Format ProjectNameProject. Die eigentliche swagger App wird dann in dem ProjectNameProject Ordner mit npm erstellt.
Durch diese Struktur haben wir im Ordner ProjectNameProject Platz um Projekt bezogene Arbeitsdateien zu speichern, und unsere App ist sauber im eigenen Ordner.
# Gehe zu dem Ordner in dem du dein neues Projekt erstellen möchtest cd the/folder/where/you/work/on/swagger/projects/ # Erstelle den neuen Ordner für das Projekt mkdir ProjectName # Wechsel in den Projekt Ordner cd ProjectName
Jetzt können wir das Grundgerüst für unser nodejs/swagger Project erstellen mit npm erstellen. Dabei wird ein neuer Ordner mit der default Projekt Struktur erstellt.
# Neues Projekt mit swagger erstellen swagger project create ProjectName
Nachdem man den create Befehl gestartet hat wird man vom Installer gefragt welches Framework für das Routing genutzt werden soll. Ich nutze hier express, aber folgende Frameworks stehen Euch zur Verfügung:
- connect
- express
- hapi
- restify
- sails
Wenn das Framework express gewählt wurde haben wir jetzt folgende Struktur in unserem Projekt Ordner:
ProjectNameProject/ProjectName/ api/ controllers/ hello_world.js README.md helpers/ README.md mocks/ README.md swagger/ swagger.yaml config/ default.yaml README.md node_modules/ ...many many folders and files ;) test/ api/ controllers/ hello_world.js README.md helpers/ README.md .gitignore app.js package-lock.json package.json README.md
Erklärung der Default Swagger-Express Projektdateien
package.json und package-lock.json
Die package-lock.json Datei wird auto generiert, daher werde ich die hier nicht weiter erläutern.
In der package.json Datei werden die Informationen zur App Definiert. Diese Informationen werden von npm genutzt um die App zu installieren.
Hier ein Beispiel wie die package.json aussieht wenn wir das Projekt aus diesem Beispiel neu erstellt haben:
{ "name": "ProjectName", "version": "0.0.1", "private": true, "description": "New Swagger API Project", "keywords": [], "author": "", "license": "", "main": "app.js", "dependencies": { "express": "^4.12.3", "swagger-express-mw": "^0.1.0" }, "devDependencies": { "should": "^7.1.0", "supertest": "^1.0.0" }, "scripts": { "start": "node app.js", "test": "swagger project test" } }
.gitignore
Hier können wir festlegen welche Dateien oder Ordner nicht mit in git commited werden wenn wir git nutzen.
app.js
Die app.js Datei ist der eigentliche App starter. wie man in der package.json sehen kann (unter “scripts” der Wert bei “start”) wird diese Datei aufgerufen, wenn wir npm start
in der CMD ausführen.
Ordner /test
Im Ordner /test findet man ein kleines Beispiel wie man integration Tests schreibt. Als Beispiel wird ein test für den Controller hello_world.js im Ordner api/controllers benutzt.
Ordner /node_modules
Hier legt npm die node_module Dateien ab wenn man ein modul für das PRoject installiert. Dieser Ordner sollte unbedingt in der .gitignore Datei eingetragen sein damit er nicht mit commited wird.
Ordner /config
Hier liegt die für das Swagger Projekt benötigkte default.yaml Datei die bestimmt wie die App gestartet wird.
Ordner /api
In diesem Ordner ligt der eignetliche App Code. Hier muss die Logik gebaut werden.
Ordner /api/controllers
Hier findet man eine beispiel Datei die einem den Einstieg in die eigene Programmierung erleichtert. Alle weiteren, eigenen Controller sollten hier abgelegt werden.
Ordner /api/helpers
Im /helpers Ordner lege ich Klassen die ich immer wieder nutzen möchte, und die Unabhängig arbeiten.
Ordner /api/mocks
Der mocks Ordner ist für den Mock Mode in swagger. Diese nkann man mit
swagger project start -m
starten. Dabei werden die Objecte aus der Swagger.yaml Struktur automatisch anhand der beschreibung erstellt. Mehr Informationen hier: (en: https://github.com/swagger-api/swagger-node/blob/master/docs/mock-mode.md
Ordner /api/swagger
Hier liegt die Konfiguration für das Swagger Routing. Alle Routen und alle Response und Result Object Strukturen für unsrere App müssen hier, in der swagger.yaml, definiert werden.
swagger project start
Swagger Projekt swagger.yaml Editor starten
swagger project edit
Tests erstellen lassen.
Swagger generiert dabei für die controller Tests, die dann im Ordner test/api/client test/api/controllers test/api/helpers abgelegt werden.
swagger project generate-test -f request
Test starten.
ACHTUNG! Nicht vergessen in den generierten tests die Variabel Werte anzupassen, sonst wird kein Test bestanden werden ;)
npm test