Added openapi spec

FullStackBulletin · Aug 1, 2023 · 5f13cf3 · 5f13cf3
1 parent b5ea9e7
commit 5f13cf3
Show file tree

Hide file tree

Showing 5 changed files with 283 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -11,6 +11,13 @@ An API to get interesting tech-related quotes (powered by GitHub pages)
 
 The base URL of the API is `https://fullStackbulletin.github.io/tech-quotes`.
 
+API Documentation is available as OpenAPI specification:
+
+  - [OpenAPI definition (YAML)](https://fullStackbulletin.github.io/tech-quotes/openapi.yml)
+  - [OpenAPI definition (JSON)](https://fullStackbulletin.github.io/tech-quotes/openapi.json)
+
+[![Open API V3](https://img.shields.io/badge/open--API-in--editor-brightgreen.svg?style=flat&label=open-api-v3)](https://editor-next.swagger.io/?url=https%3A%2F%2FfullStackbulletin.github.io%2Ftech-quotes%2Fopenapi.yml)
+
 There are some endpoints available:
 
 ### `/quotes/stats.json`
@@ -114,7 +121,7 @@ Returns
 ```
 
 
-### `/authors/stats.json`
+### `/authors/stats.json`
 
 Gets statistics abouts the authors
 
@@ -188,13 +195,6 @@ Returns
     {
       "id": 31,
       "text": "Never underestimate the bandwidth of a station wagon full of tapes hurtling down the highway",
-      "author": {
-        "id": "andrew-s-tanenbaum",
-        "name": "Andrew S. Tanenbaum",
-        "description": "Computer Scientist",
-        "wiki": "https://en.wikipedia.org/wiki/Andrew_S._Tanenbaum",
-        "url": "https://fullStackbulletin.github.io/tech-quotes/authors/andrew-s-tanenbaum.json"
-      },
       "url": "https://fullStackbulletin.github.io/tech-quotes/quotes/31.json"
     }
   ]

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -30,6 +30,7 @@
     "mkdirp": "^3.0.1",
     "slugify": "^1.6.6",
     "ts-node": "^10.9.1",
-    "typescript": "^5.1.6"
+    "typescript": "^5.1.6",
+    "yaml": "^2.3.1"
   }
-}
+}
diff --git a/scripts/build.ts b/scripts/build.ts
@@ -1,8 +1,9 @@
-import { writeFile } from 'node:fs/promises'
+import { writeFile, readFile, copyFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { mkdirp } from 'mkdirp'
 import slugify from 'slugify'
+import { parse } from 'yaml'
 import quotes, { type Quote, type Author, type AuthorDescription, type RawQuote, type AuthorWithQuotes } from '../src/quotes.js'
 
 const GH_PAGES_URL = 'https://fullStackbulletin.github.io/tech-quotes'
@@ -65,6 +66,11 @@ function makeAuthor (name: string, description: AuthorDescription, wiki?: `https
   }
 }
 
+function removeAuthorFromQuote (quote: Quote): Omit<Quote, 'author'> {
+  const { author, ...rest } = quote
+  return rest
+}
+
 const all = {
   metadata: {
     total: quotes.length,
@@ -86,11 +92,11 @@ for (const quote of all.quotes) {
 
   const authorEntry = authorsWithQuotes.get(quote.author.id)
   if (typeof authorEntry !== 'undefined') {
-    authorEntry.quotes.push(quote)
+    authorEntry.quotes.push(removeAuthorFromQuote(quote))
   } else {
     authorsWithQuotes.set(quote.author.id, {
       ...quote.author,
-      quotes: [quote]
+      quotes: [removeAuthorFromQuote(quote)]
     })
   }
 
@@ -126,3 +132,15 @@ const allAuthors = {
 
 await writeFile(`${authorsPath}/all.json`, JSON.stringify(allAuthors, null, 2))
 console.log(`Written ${authorsPath}/all.json`)
+
+// copy open api file and converts it to json
+const openApiPath = join(currentDir, '..', 'src', 'openapi.yml')
+const openApiDestYaml = join(destPath, 'openapi.yml')
+await copyFile(openApiPath, openApiDestYaml)
+console.log(`Written ${openApiDestYaml}`)
+
+const openApiYaml = await readFile(openApiPath, 'utf-8')
+const openApiJson = parse(openApiYaml)
+const openApiDestJson = join(destPath, 'openapi.json')
+await writeFile(openApiDestJson, JSON.stringify(openApiJson, null, 2))
+console.log(`Written ${openApiDestJson}`)
diff --git a/src/openapi.yml b/src/openapi.yml
@@ -0,0 +1,234 @@
+openapi: 3.1.0
+
+info:
+  title: Tech Quotes API
+  version: 1.0.0
+  description: |-
+    A simple API to get inspiring tech quotes.
+
+    Source code on GitHub: https://github.com/FullStackBulletin/tech-quotes
+  license:
+    name: MIT
+    url: https://raw.githubusercontent.com/FullStackBulletin/tech-quotes/main/LICENSE
+
+servers:
+  - url: https://fullStackbulletin.github.io/tech-quotes
+    description: GitHub Pages
+
+tags:
+  - name: quotes
+    description: Quotes
+  - name: authors
+    description: Authors
+
+paths:
+  /quotes/stats.json:
+    get:
+      tags:
+        - quotes
+      summary: Get quotes stats
+      description: Get quotes stats
+      operationId: getQuotesStats
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/QuotesStats"
+  /quotes/all.json:
+    get:
+      tags:
+        - quotes
+      summary: Get all quotes
+      description: Get all quotes
+      operationId: getAllQuotes
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AllQuotes"
+  /quotes/{quoteId}.json:
+    get:
+      tags:
+        - quotes
+      summary: Get a single quote by ID
+      description: Get a single quote by ID
+      operationId: getQuote
+      parameters:
+        - in: path
+          name: quoteId
+          schema:
+            type: integer
+          required: true
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Quote"
+  /authors/stats.json:
+    get:
+      tags:
+        - authors
+      summary: Get authors stats
+      description: Get authors stats
+      operationId: getAuthorsStats
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthorsStats"
+  /authors/all.json:
+    get:
+      tags:
+        - authors
+      summary: Get all authors
+      description: Get all authors
+      operationId: getAllAuthors
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AllAuthors"
+  /authors/{authorId}.json:
+    get:
+      tags:
+        - "authors"
+      summary: Get a single author by ID
+      description: Get a single author by ID
+      operationId: getAuthor
+      parameters:
+        - in: path
+          name: authorId
+          schema:
+            type: string
+          required: true
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AuthorWithQuotes"
+
+components:
+  schemas:
+    QuoteWithoutAuthor:
+      type: object
+      properties:
+        id:
+          type: integer
+          description: Quote ID
+        text:
+          type: string
+          description: Quote text
+        url:
+          type: string
+          description: URL to retrieve the quote
+    Quote:
+      allOf:
+        - $ref: "#/components/schemas/QuoteWithoutAuthor"
+      type: object
+      properties:
+        author:
+          $ref: "#/components/schemas/Author"
+    Author:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Author ID
+        name:
+          type: string
+          description: Author name
+        description:
+          type: string
+          description: Author description
+        wiki:
+          type: string
+          description: URL to Wikipedia page
+          nullable: true
+        url:
+          type: string
+          description: URL to retrieve author
+    QuotesStats:
+      type: object
+      properties:
+        total:
+          type: integer
+          description: Total number of quotes
+        all:
+          type: string
+          description: URL to retrieve all quotes
+        first:
+          type: string
+          description: URL to retrieve first quote
+        last:
+          type: string
+          description: URL to retrieve last quote
+        urlPrefix:
+          type: string
+          description: URL prefix to retrieve quotes
+    AllQuotes:
+      type: object
+      properties:
+        metadata:
+          type: object
+          properties:
+            total:
+              type: integer
+              description: Total number of quotes
+            first:
+              type: integer
+              description: First id of a quote
+            last:
+              type: integer
+              description: Last id of a quote
+        quotes:
+          type: array
+          items:
+            $ref: "#/components/schemas/Quote"
+          description: the list of all quotes
+    AuthorsStats:
+      type: object
+      properties:
+        total:
+          type: integer
+          description: Total number of authors
+        all:
+          type: string
+          description: URL to retrieve all authors
+        urlPrefix:
+          type: string
+          description: URL prefix to retrieve authors
+    AllAuthors:
+      type: object
+      properties:
+        metadata:
+          type: object
+          properties:
+            total:
+              type: integer
+              description: Total number of authors
+        authors:
+          type: array
+          items:
+            type: string
+          description: the list of all author IDs
+    AuthorWithQuotes:
+      type: object
+      allOf:
+        - $ref: "#/components/schemas/Author"
+      properties:
+        quotes:
+          type: array
+          items:
+            $ref: "#/components/schemas/QuoteWithoutAuthor"