Skip to content

Commit 1bcc49b

Browse files
iamfiropoiamfiropo
committed
chore(swagger): document api endpoints
[Finishes #167503820]
1 parent 55ffde0 commit 1bcc49b

20 files changed

+416
-77
lines changed

‎README.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,17 @@ etc
6464
6565
> [Repository](https://github.com/Johnpeace/PropertyProLite)
6666
67-
> [API Documentation]()
67+
> [Swagger API Docs](https://propertyprolite.herokuapp.com/api/v1/api-docs)
6868
69-
> Project References
69+
## Project References
7070
* [Dave Sag](https://itnext.io/wiring-up-an-api-server-with-express-and-swagger-9bffe0a0d6bd)
71+
* [Swagger Documentation](https://swagger.io/)
72+
* [Mocha](https://mochajs.org/)
73+
* [ESLint](https://eslint.org/)
74+
* [node-postgres](http://node-postgres.com)
75+
* [Airbnb](https://github.com/airbnb/javascript)
76+
* [Cloudinary](https://cloudinary.com)
77+
* [Heroku](https://heroku.com/)
7178

7279

7380
## Author

‎docs/property.yml‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
paths:
2+
/api/v1/property:
3+
post:
4+
tags:
5+
- Property
6+
summary: Create a property advert
7+
security:
8+
- bearerAuth: []
9+
produces:
10+
- application/json
11+
parameters:
12+
- in: body
13+
name: property
14+
description: It enables a user to create a property
15+
schema:
16+
$ref: '#/definitions/property'
17+
responses:
18+
201:
19+
description: Successfully created
20+
400:
21+
description: Please fill all the required fields
22+
403:
23+
description: Token required. Please sign in or register as a user
24+
500:
25+
description: Internal server error
26+
get:
27+
tags:
28+
- Property
29+
summary: Get all properties
30+
security:
31+
- bearerAuth: []
32+
produces:
33+
- application/json
34+
responses:
35+
200:
36+
description: Got all property adverts successfully
37+
403:
38+
description: Token required. Please sign in or register as a user
39+
404:
40+
description: No property found
41+
500:
42+
description: Internal server error
43+
44+
/api/v1/property/{property_id}:
45+
get:
46+
tags:
47+
- Property
48+
summary: View a specific property advert
49+
security:
50+
- bearerAuth: []
51+
produces:
52+
- application/json
53+
parameters:
54+
- in: path
55+
name: property_id
56+
schema:
57+
type: integer
58+
required: true
59+
description: It enables a user to view a specific property advert
60+
responses:
61+
200:
62+
description: Got the specific property advert successfully
63+
403:
64+
description: Token required. Please sign in or register as a user
65+
404:
66+
description: No property found
67+
500:
68+
description: Internal server error
69+
70+
patch:
71+
tags:
72+
- Property
73+
summary: Update property data
74+
security:
75+
- bearerAuth: []
76+
produces:
77+
- application/json
78+
parameters:
79+
- in: path
80+
name: property_id
81+
schema:
82+
type: integer
83+
required: true
84+
description: property advert to modify
85+
- in: body
86+
name: property
87+
description: fields to update
88+
schema:
89+
$ref: '#/definitions/property'
90+
responses:
91+
200:
92+
description: Updated Successfully
93+
403:
94+
description: Token required. Please sign in or register as a user
95+
404:
96+
description: Property not found
97+
500:
98+
description: Internal server error
99+
100+
delete:
101+
tags:
102+
- Property
103+
summary: Delete a property advert
104+
security:
105+
- bearerAuth: []
106+
produces:
107+
- application/json
108+
parameters:
109+
- in: path
110+
name: property_id
111+
schema:
112+
type: integer
113+
required: true
114+
description: property advert to delete
115+
responses:
116+
200:
117+
description: Deleted Successfully
118+
403:
119+
description: Token required. Please sign in or register as a user
120+
404:
121+
description: Property id not found
122+
500:
123+
description: Internal server error
124+
125+
/api/v1/properties:
126+
get:
127+
tags:
128+
- Property
129+
summary: Get all property advertisement offering a specific type of property
130+
security:
131+
- bearerAuth: []
132+
produces:
133+
- application/json
134+
parameters:
135+
- in: query
136+
name: type
137+
schema:
138+
type: string
139+
required: true
140+
description: The number of specific type of property to return
141+
responses:
142+
200:
143+
description: Got the property type successfully
144+
400:
145+
description: No valid query detected e.g properties?type=duplex
146+
403:
147+
description: Token required. Please sign in or register as a user
148+
404:
149+
description: Property type not found. Check the property type query value
150+
500:
151+
description: Internal server error
152+
153+
/api/v1/property/{property_id}/sold:
154+
patch:
155+
tags:
156+
- Property
157+
summary: Mark a property as sold so users know it’s no longer available
158+
security:
159+
- bearerAuth: []
160+
produces:
161+
- application/json
162+
parameters:
163+
- in: path
164+
name: property_id
165+
schema:
166+
type: integer
167+
required: true
168+
description: property advert to modify
169+
- in: body
170+
name: property status
171+
description: change status to sold
172+
schema:
173+
$ref: '#/definitions/propertyStatus'
174+
responses:
175+
200:
176+
description: Mark as sold successfully
177+
403:
178+
description: Token required. Please sign in or register as a user
179+
404:
180+
description: Property not found
181+
500:
182+
description: Internal server error
183+
184+
definitions:
185+
property:
186+
type: object
187+
required:
188+
- price
189+
- state
190+
- city
191+
- address
192+
- type
193+
- image_url
194+
properties:
195+
price:
196+
type: real
197+
example: 24567.00
198+
state:
199+
type: string
200+
example: Lagos
201+
city:
202+
type: string
203+
example: Oworo
204+
address:
205+
type: string
206+
example: 2, kokumo
207+
type:
208+
type: string
209+
example: duplex
210+
image_url:
211+
type: string
212+
example: https://pixabay.com/photos/portrait-woman-lady-coffee-bar-4246954/
213+
214+
propertyStatus:
215+
type: object
216+
required:
217+
- status
218+
properties:
219+
status:
220+
type: string
221+
example: sold
222+
readOnly: true

‎docs/swagger.js‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
const options = {
2+
definition: {
3+
swagger: '2.0',
4+
info: {
5+
title: 'PropertyProLite API',
6+
version: '2.0.0',
7+
description: 'API docs for PropertyProLite Application'
8+
},
9+
securityDefinitions: {
10+
bearerAuth: {
11+
name: 'Authorization',
12+
in: 'header',
13+
type: 'apiKey',
14+
},
15+
},
16+
schemes: ['http'],
17+
},
18+
apis: ['./docs/*.yml'],
19+
};
20+
21+
export default options;

‎docs/users.yml‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
paths:
2+
/api/v1/auth/signup:
3+
post:
4+
tags:
5+
- User
6+
summary: creates a new user
7+
produces:
8+
- application/json
9+
parameters:
10+
- in: body
11+
name: sign up
12+
description: It enables a user to create an account
13+
required: false
14+
schema:
15+
$ref: '#/definitions/signUp'
16+
responses:
17+
201:
18+
description: Successfully created
19+
400:
20+
description: Please fill all the required fields
21+
409:
22+
description: Email already exist
23+
500:
24+
description: Internal server error
25+
26+
/api/v1/auth/signin:
27+
post:
28+
tags:
29+
- User
30+
summary: sign in a user
31+
produces:
32+
- application/json
33+
parameters:
34+
- in: body
35+
name: sign in
36+
description: It enables a user to sign in
37+
required: false
38+
schema:
39+
$ref: '#/definitions/signIn'
40+
responses:
41+
200:
42+
description: User sign in successfully
43+
400:
44+
description: Enter valid password
45+
401:
46+
description: Wrong password. Please try again
47+
404:
48+
description: Sorry!!! We do not recognize this email
49+
500:
50+
description: Internal server error
51+
52+
definitions:
53+
signUp:
54+
type: object
55+
required:
56+
- email
57+
- first_name
58+
- last_name
59+
- password
60+
- phone_number
61+
- address
62+
- is_admin
63+
properties:
64+
email:
65+
type: string
66+
example: test@test.com
67+
first_name:
68+
type: string
69+
example: Ropo
70+
last_name:
71+
type: string
72+
example: Olatujoye
73+
password:
74+
type: string
75+
example: password1
76+
phone_number:
77+
type: integer
78+
example: 08089876543
79+
address:
80+
type: string
81+
example: 2, ologo street
82+
is_admin:
83+
type: boolean
84+
example: true
85+
86+
signIn:
87+
type: object
88+
required:
89+
- email
90+
- password
91+
properties:
92+
email:
93+
type: string
94+
example: test@test.com
95+
password:
96+
type: string
97+
example: password1

‎package.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,10 @@
3131
"moment": "^2.24.0",
3232
"pg": "^7.11.0",
3333
"regenerator-runtime": "^0.13.2",
34-
"socket.io": "^2.2.0"
34+
"socket.io": "^2.2.0",
35+
"swagger-express-router": "^1.0.0",
36+
"swagger-jsdoc": "^3.3.0",
37+
"swagger-ui-express": "^4.0.7"
3538
},
3639
"devDependencies": {
3740
"@babel/cli": "^7.4.4",

‎server.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,12 @@ import logger from 'morgan';
33
import Debug from 'debug';
44
import cors from 'cors';
55
import { config } from 'dotenv';
6+
import swaggerJSDoc from 'swagger-jsdoc';
7+
import swaggerUI from 'swagger-ui-express';
68
import 'regenerator-runtime/runtime';
79
import './server/config/cloudinary';
810
import Route from './server/routes/route';
11+
import options from './docs/swagger';
912

1013
config();
1114

@@ -29,6 +32,9 @@ app.get('/api/v1', (req, res) => {
2932
const router = express.Router();
3033
app.use('/api/v1', Route(logger, router));
3134

35+
const swaggerSpec = swaggerJSDoc(options);
36+
app.use('/api/v1/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerSpec));
37+
3238
app.use((req, res) => {
3339
res.status(404).json({
3440
status: 404,

0 commit comments

Comments
 (0)