Swagger API sample

This is a reference implementation of a full REST API server in a Design Driven Development (DDD) fashion on top of Swagger, Express and Mongoose. Instead of a test driven development (TDD) or other development approaches, DDD begins with the swagger document first, then tests and finally the code. The design is strictly resource oriented, with HTTP verbs as methods. The used REST approach start from collections name to manage resources. Resources are the basic item that a client should manage, usually identified by an _id. VERBs are used to manage the data, as explained below:

• GET retrieve resources
• POST creates a new resource
• PUT updates a resource
• DELETE remove a resource

Here is an example for a generic users collection

• GET /users Get list of all users
• GET /users?name=John&surname=Smith Get list of users called John Smith
• GET /users/1 Get User of Id 1
• PUT /users/2 Update User with Id 2
• POST /users/ Create a new User
• DELETE /users/1 Delete User with Id 1

Special methods could be added to implement specific functionalities over the data of a single resource (like a login that uses a username and a password of a user resource). the HTTP verb is POST to passing parameters in body. Some example for users (the {} identifies the body parameters):

• login: POST /users/login {username, password}
• logout: POST /users/logout {username}
• forgotten password: POST /users/password/forgotten {username}
• reset a forgotten password: POST /users/password/change {username, token, newpassword}

This design facilitates writing APIs that are loosely coupled with clients and easier to design, handle, review, and test. Please, have a look at swaggerize-express (https://github.com/krakenjs/swaggerize-express) and swaggering-mongoose (https://github.com/pblabs/swaggering-mongoose) for more details.

The API is for a simple TAG service that creates,gets, lists, deletes, and updates a set of tags. A tag could have one or more realted user ids (called identity). A tag has a name, if not submitted, it is autogenerated.

Files & Folders

Source code

The server setup and configuration logic are in the server and config folders. The routes folder contains the endpoints business logic, while models contains the setup and low-level business code for data (such as validation, data mangling and so on...).

API definitions

The swagger folder contains the definitions for API and models . Inside, API definitions are in the api folder. The models folder contains the collections' models, used to define the MongoDB collections or API response. The forms folder contains the models used for data input. Please, keep in mind that this definitions are not only for documentation, but also used for endopint definitions, form validation and model definitions too.

Setup & Run notes

• Get dependencies: $ npm install
• Start the server: $ npm start
• Build the container (you should have Docker running): $ ./container/setup.sh
• Use curl, resty, Postman, restlet or such to play with those endpoints

Unit testing

• To run available unit tests for endpoints business logic (no integration test): $ npm run test
• To test only the Swagger documentation: $ npm run api:test

API preview

The online swagger editor could be used to get a preview of the API. The editor expects a bundle (a file with any $ref resolved) copy of the API. The following command could be used to bundle an API: $ npm run api:bundle -- api/.yaml .json When ready, open the bundle file and copy its content. Then, on the online swagger editor, select File -> Paste JSON... and paste the content into the modal window. Press Import to load the definitions. If the API server is available, the right pane could be used also to preview the server response.

Some SWAGGER tools

• swagger-cli $ npm install -g swagger-cli
• Validate a definition, e.g.: $ swagger validate swagger/api/.yaml
• Resolve any $ref in a single file $ swagger bundle swagger/api/.yaml -o .json
• Online editor http://editor.swagger.io