Merge branch 'release/1.5.1'

hirsch88 · hirsch88 · commit 37db5bf21dbf · 2017-05-24T23:07:35.000+02:00
diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@ A delightful way to building a RESTful API with NodeJs & TypeScript.
 - **Easy Data Seeding** with our own factories.
 - **Custom Commands** are also available in our setup and really easy to use.
 - **Smart Validation** thanks to [class-validator](https://github.com/pleerock/class-validator) with some nice annotations.
+- **Inline Swagger Documentation** thanks to [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc)
 
 ## Getting Started
 ### Prerequisites
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "express-typescript-boilerplate",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "A delightful way to building a RESTful API with NodeJs & TypeScript",
   "main": "src/index.ts",
   "scripts": {
@@ -104,6 +104,7 @@
     "require-dir": "^0.3.1",
     "run-sequence": "^1.2.2",
     "serve-favicon": "^2.4.3",
+    "swagger-jsdoc": "^1.9.4",
     "swagger-ui-express": "^2.0.0",
     "ts-jest": "^20.0.4",
     "ts-node": "^3.0.4",
diff --git a/src/api/controllers/HomeController.ts b/src/api/controllers/HomeController.ts
@@ -5,14 +5,23 @@ import { injectable } from 'inversify';
 /**
  * HomeController is a public controller to give some
  * information about this api
- *
- * @export
- * @class HomeController
  */
 @injectable()
-@Controller('/')
+@Controller('/v1')
 export class HomeController {
 
+    /**
+     * @swagger
+     * /:
+     *   get:
+     *     tags:
+     *     - Root
+     *     summary: Show API information
+     *     description: Gets the api information
+     *     responses:
+     *       200:
+     *         description: api information
+     */
     @Get('/')
     public get( @Response() res: express.Response): any {
         const pkg = require('../../../package.json');
diff --git a/src/api/controllers/UserController.ts b/src/api/controllers/UserController.ts
@@ -11,50 +11,223 @@ const log = new Log('api:ctrl.UserController');
 /**
  * UserController is in charge of the user resource and should
  * provide all crud actions.
- *
- * @export
- * @class UserController
  */
 @injectable()
 @Controller('/v1/user', authenticate)
 export class UserController {
 
     constructor( @inject(Types.UserService) private userService: UserService) { }
 
+    /**
+     * @swagger
+     * /user:
+     *   get:
+     *     tags:
+     *     - User
+     *     summary: List all users
+     *     description: Returns users
+     *     security:
+     *     - JWT: []
+     *     responses:
+     *       200:
+     *         description: List of all users
+     *         schema:
+     *           type: object
+     *           title: UserResponse
+     *           properties:
+     *             success:
+     *               type: boolean
+     *             message:
+     *               type: string
+     *             data:
+     *               type: array
+     *               items:
+     *                 $ref: "#/definitions/User"
+     */
     @Get('/')
     public async findAll( @Response() res: my.Response): Promise<any> {
         log.debug('findAll');
         const users = await this.userService.findAll();
         return res.found(users.toJSON());
     }
 
+    /**
+     * @swagger
+     * /user:
+     *   post:
+     *     tags:
+     *     - User
+     *     summary: Create new user
+     *     description: Creates new user and returns him
+     *     security:
+     *     - JWT: []
+     *     parameters:
+     *     - in: "body"
+     *       name: "body"
+     *       required: true
+     *       schema:
+     *         $ref: "#/definitions/NewUser"
+     *     responses:
+     *       200:
+     *         description: New user
+     *         schema:
+     *           type: object
+     *           title: UserResponse
+     *           properties:
+     *             success:
+     *               type: boolean
+     *             message:
+     *               type: string
+     *             data:
+     *               $ref: "#/definitions/User"
+     */
     @Post('/')
     public async create( @Response() res: my.Response, @RequestBody() body: any): Promise<any> {
         log.debug('create ', body);
         const user = await this.userService.create(body);
         return res.created(user.toJSON());
     }
 
+    /**
+     * @swagger
+     * /user/me:
+     *   get:
+     *     tags:
+     *     - User
+     *     summary: Get logged in user
+     *     description: Returns logged in user
+     *     security:
+     *     - JWT: []
+     *     responses:
+     *       200:
+     *         description: User
+     *         schema:
+     *           type: object
+     *           title: UserResponse
+     *           properties:
+     *             success:
+     *               type: boolean
+     *             message:
+     *               type: string
+     *             data:
+     *               type: object
+     *               $ref: "#/definitions/User"
+     */
     @Get('/me', populateUser)
     public async findMe( @Request() req: my.Request, @Response() res: my.Response): Promise<any> {
         log.debug('findMe');
         return res.found(req.user);
     }
 
+    /**
+     * @swagger
+     * /user/{id}:
+     *   get:
+     *     tags:
+     *     - User
+     *     summary: Get user
+     *     description: Returns a user
+     *     security:
+     *     - JWT: []
+     *     responses:
+     *       200:
+     *         description: User
+     *         schema:
+     *           type: object
+     *           title: UserResponse
+     *           properties:
+     *             success:
+     *               type: boolean
+     *             message:
+     *               type: string
+     *             data:
+     *               type: object
+     *               $ref: "#/definitions/User"
+     */
     @Get('/:id')
     public async findOne( @Response() res: my.Response, @RequestParam('id') id: string): Promise<any> {
         log.debug('findOne ', id);
         const user = await this.userService.findOne(parseInt(id, 10));
         return res.found(user.toJSON());
     }
 
+    /**
+     * @swagger
+     * /user/{id}:
+     *   put:
+     *     tags:
+     *     - User
+     *     summary: Update user
+     *     description: Returns a user
+     *     security:
+     *     - JWT: []
+     *     parameters:
+     *     - name: "id"
+     *       in: "path"
+     *       description: "ID of user to return"
+     *       required: true
+     *       type: "integer"
+     *       format: "int64"
+     *     - in: "body"
+     *       name: "body"
+     *       description: "User object"
+     *       required: true
+     *       schema:
+     *         $ref: "#/definitions/NewUser"
+     *     responses:
+     *       200:
+     *         description: User
+     *         schema:
+     *           type: object
+     *           title: UserResponse
+     *           properties:
+     *             success:
+     *               type: boolean
+     *             message:
+     *               type: string
+     *             data:
+     *               type: object
+     *               $ref: "#/definitions/User"
+     */
     @Put('/:id')
     public async update( @Response() res: my.Response, @RequestParam('id') id: string, @RequestBody() body: any): Promise<any> {
         log.debug('update ', body);
         const user = await this.userService.update(parseInt(id, 10), body);
         return res.updated(user.toJSON());
     }
 
+    /**
+     * @swagger
+     * /user/{id}:
+     *   delete:
+     *     tags:
+     *     - User
+     *     summary: Delete user
+     *     description: Returns a user
+     *     security:
+     *     - JWT: []
+     *     parameters:
+     *     - name: "id"
+     *       in: "path"
+     *       description: "ID of user to return"
+     *       required: true
+     *       type: "integer"
+     *       format: "int64"
+     *     responses:
+     *       200:
+     *         description: User
+     *         schema:
+     *           type: object
+     *           title: UserResponse
+     *           properties:
+     *             success:
+     *               type: boolean
+     *             message:
+     *               type: string
+     *             data:
+     *               type: object
+     *               example:
+     */
     @Delete('/:id')
     public async destroy( @Response() res: my.Response, @RequestParam('id') id: string): Promise<any> {
         log.debug('destroy ', id);
diff --git a/src/api/models/User.ts b/src/api/models/User.ts
@@ -45,3 +45,43 @@ export class User extends Bookshelf.Model<User> {
 
 }
 
+/**
+ * @swagger
+ * definitions:
+ *   NewUser:
+ *     type: object
+ *     properties:
+ *       firstName:
+ *         type: string
+ *       lastName:
+ *         type: string
+ *       email:
+ *         type: string
+ *       picture:
+ *         type: string
+ */
+
+/**
+ * @swagger
+ * definitions:
+ *   User:
+ *     type: object
+ *     properties:
+ *       id:
+ *         type: "integer"
+ *         format: "int64"
+ *       firstName:
+ *         type: string
+ *       lastName:
+ *         type: string
+ *       email:
+ *         type: string
+ *       picture:
+ *         type: string
+ *       updatedAt:
+ *         type: string
+ *         format: date-time
+ *       createdAt:
+ *         type: string
+ *         format: date-time
+ */
diff --git a/src/core/Bootstrap.ts b/src/core/Bootstrap.ts
@@ -79,11 +79,31 @@ export class Bootstrap {
      */
     static setupSwagger(app: express.Application): express.Application {
         if (Environment.get<string>('SWAGGER_ENABLED') === 'true') {
-            const basePath = __dirname.substring(0, __dirname.indexOf('/src/') + 4);
+            const swaggerJSDoc = require('swagger-jsdoc');
+            const basePath = __dirname.substring(0, __dirname.indexOf('/src/'));
+
+            const swaggerDefinition = require(basePath + '/swagger.json');
+            const packageJson = require(basePath + '/package.json');
+            swaggerDefinition.info = {
+                title: packageJson.name,
+                description: packageJson.description,
+                version: packageJson.version
+            };
+
+            const options = {
+                swaggerDefinition: swaggerDefinition,
+                apis: [
+                    './src/api/models/**/*.ts',
+                    './src/api/controllers/**/*.ts'
+                ]
+            };
+
+            // Initialize swagger-jsdoc -> returns validated swagger spec in json format
+            const swaggerSpec = swaggerJSDoc(options);
             const swaggerUi = require('swagger-ui-express');
-            const swaggerDocument = require(basePath + Environment.get<string>('SWAGGER_FILE'));
             const route = Environment.get<string>('APP_URL_PREFIX') + Environment.get<string>('SWAGGER_ROUTE');
-            app.use(route, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
+
+            app.use(route, swaggerUi.serve, swaggerUi.setup(swaggerSpec));
             log.info(`Now you can access the swagger docs under -> ${app.get('host')}:${(app.get('port'))}${route}`);
         }
         return app;
diff --git a/src/swagger.json b/src/swagger.json
diff --git a/swagger.json b/swagger.json
diff --git a/yarn.lock b/yarn.lock
