Skip to content

Commit ea8c4dc

Browse files
dave-okdave-ok
authored
Merge pull request #530 from simply-alliv/swagger-setup
feat: add initial setup for swagger with example
2 parents cc0d5b1 + 7292dac commit ea8c4dc

10 files changed

Lines changed: 282 additions & 45 deletions

File tree

‎.github/workflows/main.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ jobs:
2323
node-version: ${{ matrix.node-version }}
2424

2525
- run: npm ci
26+
- run: npm run lint
2627
- run: npm run test:ci
2728

2829
- name: Coveralls Parallel

‎package-lock.json‎

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

‎src/__test__/__snapshots__/index.test.js.snap‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Jest Snapshot v1, https://goo.gl/fbAQLP
2+
3+
exports[`Server runs Should return status 200 and render Swagger docs 1`] = `
4+
"
5+
<!-- HTML for static distribution bundle build -->
6+
<!DOCTYPE html>
7+
<html lang=\\"en\\">
8+
<head>
9+
<meta charset=\\"UTF-8\\">
10+
<title>MicroAPI | Authentication API Documentation</title>
11+
<link rel=\\"stylesheet\\" type=\\"text/css\\" href=\\"./swagger-ui.css\\" >
12+
<link rel=\\"icon\\" type=\\"image/png\\" href=\\"./favicon-32x32.png\\" sizes=\\"32x32\\" /><link rel=\\"icon\\" type=\\"image/png\\" href=\\"./favicon-16x16.png\\" sizes=\\"16x16\\" />
13+
14+
<style>
15+
html
16+
{
17+
box-sizing: border-box;
18+
overflow: -moz-scrollbars-vertical;
19+
overflow-y: scroll;
20+
}
21+
*,
22+
*:before,
23+
*:after
24+
{
25+
box-sizing: inherit;
26+
}
27+
28+
body {
29+
margin:0;
30+
background: #fafafa;
31+
}
32+
</style>
33+
</head>
34+
35+
<body>
36+
37+
<svg xmlns=\\"http://www.w3.org/2000/svg\\" xmlns:xlink=\\"http://www.w3.org/1999/xlink\\" style=\\"position:absolute;width:0;height:0\\">
38+
<defs>
39+
<symbol viewBox=\\"0 0 20 20\\" id=\\"unlocked\\">
40+
<path d=\\"M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z\\"></path>
41+
</symbol>
42+
43+
<symbol viewBox=\\"0 0 20 20\\" id=\\"locked\\">
44+
<path d=\\"M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z\\"/>
45+
</symbol>
46+
47+
<symbol viewBox=\\"0 0 20 20\\" id=\\"close\\">
48+
<path d=\\"M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z\\"/>
49+
</symbol>
50+
51+
<symbol viewBox=\\"0 0 20 20\\" id=\\"large-arrow\\">
52+
<path d=\\"M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z\\"/>
53+
</symbol>
54+
55+
<symbol viewBox=\\"0 0 20 20\\" id=\\"large-arrow-down\\">
56+
<path d=\\"M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z\\"/>
57+
</symbol>
58+
59+
60+
<symbol viewBox=\\"0 0 24 24\\" id=\\"jump-to\\">
61+
<path d=\\"M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z\\"/>
62+
</symbol>
63+
64+
<symbol viewBox=\\"0 0 24 24\\" id=\\"expand\\">
65+
<path d=\\"M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z\\"/>
66+
</symbol>
67+
68+
</defs>
69+
</svg>
70+
71+
<div id=\\"swagger-ui\\"></div>
72+
73+
<script src=\\"./swagger-ui-bundle.js\\"> </script>
74+
<script src=\\"./swagger-ui-standalone-preset.js\\"> </script>
75+
<script src=\\"./swagger-ui-init.js\\"> </script>
76+
77+
<style>
78+
.swagger-ui .topbar .download-url-wrapper { display: none } .swagger-ui .topbar { display: none }
79+
</style>
80+
</body>
81+
82+
</html>
83+
"
84+
`;

‎src/__test__/index.test.js‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@ import app from "../";
22
import request from "supertest";
33

44
describe("Server runs", () => {
5-
it("should return a status of 200", async () => {
6-
const response = await request(app).get("/");
7-
expect(response.status).toBe(200);
5+
test("Should return status 200 and render Swagger docs", async () => {
6+
const res = await request(app).get("/");
7+
expect(res.status).toBe(200);
8+
expect(res.text).toMatchSnapshot();
89
});
910
it("should return a status of 404", async () => {
1011
const response = await request(app).get("/garbledygook");

‎src/index.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import express from "express";
22
import cors from "cors";
33
import CustomError from "./utils/customError";
44
import errorHandler from "./utils/errorhandler";
5+
import { docRouter } from "./routes";
56

67
// create express app
78
const app = express();
@@ -13,9 +14,8 @@ app.use(cors());
1314
app.use(express.json());
1415
app.use(express.urlencoded({ extended: true }));
1516

16-
app.get("/", (req, res) => {
17-
res.send("up and running!");
18-
});
17+
// docuementation routes
18+
app.use("/", docRouter);
1919

2020
// routes not found go here
2121
app.all("*", (req, res, next) => {

‎src/jsdocs/definitions/badRequest.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
definitions:
2+
# BadRequest model
3+
BadRequest:
4+
type: object
5+
properties:
6+
status:
7+
type: string
8+
example: error
9+
error:
10+
type: string
11+
example: Invalid body supplied

‎src/jsdocs/providers/google.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
paths:
2+
# Endpoint to authenticate a user
3+
/google:
4+
# GET operation
5+
get:
6+
tags:
7+
- providers
8+
9+
summary: Authenticates with Google
10+
11+
security:
12+
- AdminToken: []
13+
14+
responses:
15+
"200":
16+
description: Successful operation
17+
schema:
18+
type: object
19+
properties:
20+
status:
21+
type: string
22+
example: success
23+
data:
24+
type: object
25+
properties:
26+
redirectUrl:
27+
type: string
28+
example: https://accounts.google.com/o/oauth2/v2/auth/oauthchooseaccount
29+
"400":
30+
description: Invalid body supplied
31+
schema:
32+
$ref: "#/definitions/BadRequest"

‎src/routes/documentation.js‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import express from "express";
2+
import swaggerUi from "swagger-ui-express";
3+
import swaggerSpec from "../utils/swaggerSpec";
4+
5+
const docRouter = express.Router();
6+
7+
const swaggerUiOptions = {
8+
customSiteTitle: "MicroAPI | Authentication API Documentation",
9+
customCss: ".swagger-ui .topbar { display: none }",
10+
};
11+
12+
// use swagger-ui-express for your app documentation endpoint
13+
docRouter.use("/", swaggerUi.serve);
14+
docRouter.get("/", swaggerUi.setup(swaggerSpec, swaggerUiOptions));
15+
docRouter.get("/documentation", swaggerUi.setup(swaggerSpec, swaggerUiOptions));
16+
17+
export default docRouter;

‎src/routes/index.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
import docRouter from "./documentation";
2+
3+
export { docRouter };

0 commit comments

Comments
 (0)