Skip to content

Commit 1df511a

Browse files
jjjimenez100jjjimenez100
authored
Add swagger documentation for rides api v1 (#1)
The PR adds a swagger documentation for the Rides API, with a new dependency to swagger-ui-express. Web documentation can be viewed with /api-documentation/v1. Upon API deployment, the documentation should also be available. The swagger file is prefixed with api-v as to indicate the API version it is documenting, since it is possible to have multiple documentation support multiple versions of the API.
1 parent 5349079 commit 1df511a

File tree

4 files changed

+237
-1
lines changed

4 files changed

+237
-1
lines changed

‎package-lock.json

Lines changed: 13 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@
1818
"dependencies": {
1919
"body-parser": "^1.19.0",
2020
"express": "^4.16.4",
21-
"sqlite3": "^4.0.6"
21+
"sqlite3": "^4.0.6",
22+
"swagger-ui-express": "^4.1.4"
2223
},
2324
"devDependencies": {
2425
"mocha": "^6.1.4",

‎src/app.js

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,14 @@ const app = express();
66
const bodyParser = require('body-parser');
77
const jsonParser = bodyParser.json();
88

9+
const swaggerUI = require('swagger-ui-express');
10+
const swaggerFile = require('./resources/api-v1-swagger.json');
11+
912
module.exports = (db) => {
1013
app.get('/health', (req, res) => res.send('Healthy'));
1114

15+
app.use('/api-documentation/v1', swaggerUI.serve, swaggerUI.setup(swaggerFile));
16+
1217
app.post('/rides', jsonParser, (req, res) => {
1318
const startLatitude = Number(req.body.start_lat);
1419
const startLongitude = Number(req.body.start_long);

‎src/resources/api-v1-swagger.json

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"description": "Backend API for rides",
5+
"version": "1.0.0",
6+
"title": "Rides",
7+
"contact": {
8+
"email": "jimenez.johnjoshua.jjj@gmail.com"
9+
}
10+
},
11+
"definitions": {
12+
"RideOutput": {
13+
"type": "object",
14+
"required": [
15+
"startLat",
16+
"startLong",
17+
"endLat",
18+
"endLong",
19+
"riderName",
20+
"driverName",
21+
"driverVehicle"
22+
],
23+
"properties": {
24+
"rideID": {
25+
"type": "integer",
26+
"example": 1
27+
},
28+
"startLat": {
29+
"type": "integer",
30+
"minimum": -90,
31+
"maximum": 90,
32+
"example": 90
33+
},
34+
"startLong": {
35+
"type": "integer",
36+
"minimum": -180,
37+
"maximum": 180,
38+
"example": 180
39+
},
40+
"endLat": {
41+
"type": "integer",
42+
"minimum": -90,
43+
"maximum": 90,
44+
"example": -90
45+
},
46+
"endLong": {
47+
"type": "integer",
48+
"minimum": -180,
49+
"maximum": 180,
50+
"example": -180
51+
},
52+
"riderName": {
53+
"type": "string",
54+
"example": "Joshua"
55+
},
56+
"driverName": {
57+
"type": "string",
58+
"example": "John"
59+
},
60+
"driverVehicle": {
61+
"type": "string",
62+
"example": "Truck"
63+
},
64+
"created": {
65+
"type": "string",
66+
"example": "2020-10-27 13:23:33"
67+
}
68+
}
69+
},
70+
"RideInput": {
71+
"type": "object",
72+
"required": [
73+
"start_lat",
74+
"start_long",
75+
"end_lat",
76+
"end_long",
77+
"rider_name",
78+
"driver_name",
79+
"driver_vehicle"
80+
],
81+
"properties": {
82+
"start_lat": {
83+
"type": "integer",
84+
"minimum": -90,
85+
"maximum": 90,
86+
"example": 90
87+
},
88+
"start_long": {
89+
"type": "integer",
90+
"minimum": -180,
91+
"maximum": 180,
92+
"example": 180
93+
},
94+
"end_lat": {
95+
"type": "integer",
96+
"minimum": -90,
97+
"maximum": 90,
98+
"example": -90
99+
},
100+
"end_long": {
101+
"type": "integer",
102+
"minimum": -180,
103+
"maximum": 180,
104+
"example": -180
105+
},
106+
"rider_name": {
107+
"type": "string",
108+
"example": "Joshua"
109+
},
110+
"driver_name": {
111+
"type": "string",
112+
"example": "John"
113+
},
114+
"driver_vehicle": {
115+
"type": "string",
116+
"example": "Truck"
117+
}
118+
}
119+
}
120+
},
121+
"paths": {
122+
"/health": {
123+
"get": {
124+
"summary": "Health check endpoint for the server",
125+
"description": "Checks if the server is running",
126+
"operationId": "healthcheck",
127+
"responses": {
128+
"200": {
129+
"description": "Server is up and running"
130+
}
131+
}
132+
}
133+
},
134+
135+
"/rides": {
136+
"get": {
137+
"summary": "Get all saved rides",
138+
"description": "Get all saved rides",
139+
"produces": [
140+
"application/json"
141+
],
142+
"operationId": "getRides",
143+
"responses": {
144+
"200": {
145+
"schema": {
146+
"type": "array",
147+
"items": {
148+
"$ref": "#/definitions/RideOutput"
149+
}
150+
},
151+
"description": "Successful operation"
152+
}
153+
}
154+
},
155+
"post": {
156+
"summary": "Add a new ride",
157+
"description": "Add a new ride",
158+
"operationId": "addRide",
159+
"consumes": [
160+
"application/json"
161+
],
162+
"produces": [
163+
"application/json"
164+
],
165+
"parameters": [
166+
{
167+
"in": "body",
168+
"name": "body",
169+
"description": "Rider object that needs to be added",
170+
"required": true,
171+
"schema": {
172+
"$ref": "#/definitions/RideInput"
173+
}
174+
}
175+
],
176+
"responses": {
177+
"200": {
178+
"description": "Successfully added new ride"
179+
}
180+
}
181+
}
182+
},
183+
184+
"/rides/{rideId}": {
185+
"get": {
186+
"summary": "Get saved ride by id",
187+
"description": "Get saved ride by id",
188+
"produces": [
189+
"application/json"
190+
],
191+
"parameters": [
192+
{
193+
"name": "rideId",
194+
"in": "path",
195+
"description": "ID of ride to return",
196+
"required": true,
197+
"type": "integer"
198+
}
199+
],
200+
"operationId": "getRideById",
201+
"responses": {
202+
"200": {
203+
"schema": {
204+
"type": "array",
205+
"items": {
206+
"$ref": "#/definitions/RideOutput"
207+
}
208+
},
209+
"description": "Successful operation"
210+
}
211+
}
212+
}
213+
}
214+
},
215+
"host": "localhost:8010",
216+
"basePath": "/"
217+
}

0 commit comments

Comments
 (0)