Merge pull request #3 from Wikidata-Cameroon/dev

setup redocly and added build & watch scripts for docs. also added /api-docs endpoint

.gitignore

@@ -129,3 +129,6 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+# api docs
+public/api-docs/index.html

package.json

@@ -11,8 +11,10 @@
   "scripts": {
     "test": "jest",
     "start": "node ./dist/main.js",
-    "dev": "npx nodemon",
-    "build": "rm -rf ./dist && npx tsc",
+    "build": "npm run build:docs && rm -rf ./dist && npx tsc",
+    "dev": "npm run build:docs && npx nodemon",
+    "watch:docs": "npx @redocly/cli preview-docs ./public/api-docs/index.yaml --port=8081",
+    "build:docs": "npx @redocly/cli build-docs ./public/api-docs/index.yaml --output ./public/api-docs/index.html",
     "format": "npx prettier --config ./.prettierrc.json --write ./src",
     "format:check": "npx prettier --config ./.prettierrc.json --check ./src",
     "prepare": "npx husky install",
@@ -27,6 +29,13 @@
   ],
   "author": "Wiki mentor Africa Cameroon - Yaounde",
   "license": "ISC",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2",
+    "lint-staged": "^15.2.5",
+    "prettier": "^3.3.3"
+  },
   "devDependencies": {
     "@types/cors": "^2.8.17",
     "@types/dotenv": "^8.2.0",
@@ -35,12 +44,5 @@
     "nodemon": "^3.1.4",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.4"
-  },
-  "dependencies": {
-    "cors": "^2.8.5",
-    "dotenv": "^16.4.5",
-    "express": "^4.19.2",
-    "lint-staged": "^15.2.5",
-    "prettier": "^3.3.3"
   }
 }

public/api-docs/index.yaml

@@ -0,0 +1,19 @@
+openapi: 3.0.0
+info:
+  title: wiki-lex-match API
+  description: The API for wiki-lex-match, by Wiki mentor Africa Cameroon - Yaounde developer at rebase-code-camp.
+  version: 1.0.0
+  license:
+    name: MIT
+    url: "https://opensource.org/license/mit/"
+servers:
+  - url: http://localhost:8080
+    description: local server
+
+# paths:
+#   /:
+#     # define route paths
+
+# components:
+#   schemas:
+#     # Define any reusable components or schemas

redocly.yaml

@@ -0,0 +1,25 @@
+extends:
+  -  recommended
+
+apis:
+  main:
+    root: ./api/api-docs.yaml
+rules: 
+  operation-tag-defined: error
+  no-invalid-schema-examples: error
+  no-invalid-media-type-examples: error
+  scalar-property-missing-example: error
+  rule/operation-summary-sentence-case:
+    subject: 
+      type: Operation
+      property: summary
+    message: "Operation summary must be sentence cased."
+    assertions: 
+      pattern: /^[A-Z]+[^A-Z]+$/
+  rule/example-summary-sentence-case:
+    subject: 
+      type: Example
+      property: summary
+    message: "Example summary must be sentence cased."
+    assertions: 
+      pattern: /^[A-Z]+[^A-Z]+$/

src/main.ts

@@ -11,7 +11,7 @@ import { APP_CONF } from "./config/app-config";
     .then(() =>
       app.listen(PORT, () =>
         console.log(
-          `\nserver listening on ${env === "dev" ? "http://localhost:" : "port "}${PORT}`
+          `\nserver listening on ${env === "dev" ? "http://localhost:" : "port "}${PORT}\n`
         )
       )
     )

src/server/index.ts

@@ -20,6 +20,12 @@ export default async (app: Application) => {
       .sendFile(path.join(__dirname, "../../public/main.html"));
   });
 
+  app.get("/api-docs", (_, res) => {
+    return res
+      .status(200)
+      .sendFile(path.join(__dirname, "../../public/api-docs/index.html"));
+  });
+
   app.use("/auth", authRouter);
   app.use("/languages", languageRouter);
   app.use("/match", matchRouter);