Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update contributing guide with steps to add an api endpoint #245

Merged
merged 6 commits into from
Oct 19, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 187 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,9 +277,194 @@ The file structures in this repository should look like this :
└───another-folders

### Commit Messages
<!-- TODO

-->
We use semantic commit messages

- feat: (new feature for the user, not a new feature for build script)
- fix: (bug fix for the user, not a fix to a build script)
- docs: (changes to the documentation)
- style: (formatting, missing semi colons, etc; no production code change)
- refactor: (refactoring production code, eg. renaming a variable)
- test: (adding missing tests, refactoring tests; no production code change)
- chore: (updating grunt tasks etc; no production code change)

## Join The Project Team
<!-- TODO -->

## Add an API endpoint

This example will use `users` as a new TAG for OpenAPI, meaning we will have dedicated endpoints to get some mocked users or create new ones.

### How to add an endpoint

Endpoints should be created in a `<TOPIC>-routes.ts` file under `./modules/<TOPIC>/api` folder.
We assume `<TOPIC>` as a new TAG on OpenAPI, meaning a different category with dedicated endpoints like `address`, `countries`, `currency`, and son on... We will use `users` topic in our examples.

Example on how to create and endpoint for a new topic:

- 1 - Create a new folder with the topic name, under `./modules` folder, like `./modules/users`
- 2 - Create a new file with mocked data, under `./modules/users/data`, like `./modules/users/data/users.ts`. Example:
```javascript
const usersList = [
{
"email": "male@example.com",
"gender": "male",
"username": "user0000",
"first_name": "John",
"last_name": "Doe",
"title": "mr",
},
{
"email": "female@example.com",
"gender": "male",
"username": "user0001",
"first_name": "Hydra",
"last_name": "Smith",
"title": "mrs",
},
...
]
```
- 3 - Create an `api` folder to store the `routes` file, like `./modules/users/api/users-routes.ts`
- 4 - Create different endpoints for users. Example:

```javascript
import usersList from '../data/users';

module.exports = function (app: core.Express) {
app.get('/users', (req: Request, res: Response) => {
res.json({
users: usersList,
});
});
}
```

Note: This endpoint will fetch all mocked users stored in `./modules/users/data/users.ts`

### [How our folders are structured](#file-structures)

### How to write tests

For each module you create you will also need to create a tests folder, Inside this folder there should be a `api` and `utils`
(if you create any utils) folder.

The utils tests are fairly simple jests tests, the `api` routes tests are slightly different where you will need to add

```javascript
import request from 'supertest';
import app from 'path/to/app';
```

to your tests and make a request in your test instead of calling a normal function.

### How to run tests

run `npm test`
run `npm run test:watch` to run the tests in watch mode.

### How to add OpenAPI comments

For each endpoint you should do an OpenAPI comment, this way, you will make sure your endpoint will be reflected in swagger, as well as the response schema and type are correct.
To describe describe an endpoint as an OpenAPI comment, you should use the yaml structure like this:

- 1 - Define the path
- 2 - Define the http method referent to that path
- 3 - Define the tag in order to group all endpoints referent to the same TAG (in this case, all `users` endpoints will be grouped under the tag `Users`)
- 4 - Define a brief summary of you endpoint
- 5 - Define the response types for the endpoint (200 - OK ; 404 - Not found, etc...)
- 6 - Define the schema of the response

Note: You can define the properties of each schema or reuse a schema that already exists

Each OpenAPI comment should start with `@openapi` in order to be read by swagger and reflected on it.

Example:

```javascript
/**
* @openapi
* '/users':
* get:
* tags:
* - Users
* summary: Obtain a list of all users
* responses:
* '200':
* description: OK
* schema:
* type: array
* items:
* type: object
* properties:
* email:
* type: string
* example: example@example.com
* gender:
* type: string
* example: male
* username:
* type: string
* example: user00000
* first_name:
* type: string
* example: John
* last_name:
* type: string
* example: Doe
* title:
* type: string
* example: mr
*/
```

This describe the get endpoint that we did [here](#how-to-add-an-endpoint).

After doing the OpenAPI comment:

```javascript
import usersList from '../data/users';

module.exports = function (app: core.Express) {

/**
* @openapi
* '/users':
* get:
* tags:
* - Users
* summary: Obtain a list of all users
* responses:
* '200':
* description: OK
* schema:
* type: array
* items:
* type: object
* properties:
* email:
* type: string
* example: example@example.com
* gender:
* type: string
* example: male
* username:
* type: string
* example: user00000
* first_name:
* type: string
* example: John
* last_name:
* type: string
* example: Doe
* title:
* type: string
* example: mr
*/
app.get('/users', (req: Request, res: Response) => {
res.json({
users: usersList,
});
});
}
```
27 changes: 0 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,24 +75,6 @@ Now you should be able to make any request to that port, and get a response back

💡 If you browse to that port, you'll see our swagger documentation.


## Testing

### How to write tests
For each module you create you will also need to create a tests folder, Inside this folder there should be a `api` and `utils`
(if you create any utils) folder.

The utils tests are fairly simple jests tests, the `api` routes tests are slightly different where you will need to add
```javascript
import request from 'supertest';
import app from 'path/to/app';
```
to your tests and make a request in your test instead of calling a normal function.

### How to run tests
run `npm test`
run `npm run test:watch` to run the tests in watch mode.

## FAQ

**Q:** Are you planning to add more end points? <br />
Expand All @@ -108,15 +90,6 @@ I encourage you to contribute to ***Mocked-API***! Feel free to fork the codebas

Our contributing guide is currently WIP and available here [CONTRIBUTING GUIDE](CONTRIBUTING.md)

We use semantic commit messages
- feat: (new feature for the user, not a new feature for build script)
- fix: (bug fix for the user, not a fix to a build script)
- docs: (changes to the documentation)
- style: (formatting, missing semi colons, etc; no production code change)
- refactor: (refactoring production code, eg. renaming a variable)
- test: (adding missing tests, refactoring tests; no production code change)
- chore: (updating grunt tasks etc; no production code change)

## Sponsor

Do you like this project? Support it by donating.
Expand Down
6 changes: 3 additions & 3 deletions modules/countries/api/countries-routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,13 @@ module.exports = function (app: core.Express) {
* example: https://flagcdn.com/w320/is.png
* mapsUrl:
* type: string
* example: https://goo.gl/maps/WxFWSQuc3oamNxoE6
* example: https://goo.gl/maps/WxFWSQuc3oamNxoE6
* currencyName:
* type: string
* example: Icelandic króna
* example: Icelandic króna
* currencySymbol:
* type: string
* example: kr
* example: kr
*/
app.get('/countries/', (req: Request, res: Response) => {
res.json({
Expand Down