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