Skip to content

Commit 5f13cf3

Browse files
lmamminolmammino
committed
Added openapi spec
1 parent b5ea9e7 commit 5f13cf3

File tree

5 files changed

+283
-14
lines changed

5 files changed

+283
-14
lines changed

‎README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ An API to get interesting tech-related quotes (powered by GitHub pages)
1111

1212
The base URL of the API is `https://fullStackbulletin.github.io/tech-quotes`.
1313

14+
API Documentation is available as OpenAPI specification:
15+
16+
- [OpenAPI definition (YAML)](https://fullStackbulletin.github.io/tech-quotes/openapi.yml)
17+
- [OpenAPI definition (JSON)](https://fullStackbulletin.github.io/tech-quotes/openapi.json)
18+
19+
[![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)
20+
1421
There are some endpoints available:
1522

1623
### `/quotes/stats.json`
@@ -114,7 +121,7 @@ Returns
114121
```
115122

116123

117-
### `/authors/stats.json`
124+
### `/authors/stats.json`
118125

119126
Gets statistics abouts the authors
120127

@@ -188,13 +195,6 @@ Returns
188195
{
189196
"id": 31,
190197
"text": "Never underestimate the bandwidth of a station wagon full of tapes hurtling down the highway",
191-
"author": {
192-
"id": "andrew-s-tanenbaum",
193-
"name": "Andrew S. Tanenbaum",
194-
"description": "Computer Scientist",
195-
"wiki": "https://en.wikipedia.org/wiki/Andrew_S._Tanenbaum",
196-
"url": "https://fullStackbulletin.github.io/tech-quotes/authors/andrew-s-tanenbaum.json"
197-
},
198198
"url": "https://fullStackbulletin.github.io/tech-quotes/quotes/31.json"
199199
}
200200
]

‎package-lock.json‎

Lines changed: 17 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
"mkdirp": "^3.0.1",
3131
"slugify": "^1.6.6",
3232
"ts-node": "^10.9.1",
33-
"typescript": "^5.1.6"
33+
"typescript": "^5.1.6",
34+
"yaml": "^2.3.1"
3435
}
35-
}
36+
}

‎scripts/build.ts‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1-
import { writeFile } from 'node:fs/promises'
1+
import { writeFile, readFile, copyFile } from 'node:fs/promises'
22
import { dirname, join } from 'node:path'
33
import { fileURLToPath } from 'node:url'
44
import { mkdirp } from 'mkdirp'
55
import slugify from 'slugify'
6+
import { parse } from 'yaml'
67
import quotes, { type Quote, type Author, type AuthorDescription, type RawQuote, type AuthorWithQuotes } from '../src/quotes.js'
78

89
const GH_PAGES_URL = 'https://fullStackbulletin.github.io/tech-quotes'
@@ -65,6 +66,11 @@ function makeAuthor (name: string, description: AuthorDescription, wiki?: `https
6566
}
6667
}
6768

69+
function removeAuthorFromQuote (quote: Quote): Omit<Quote, 'author'> {
70+
const { author, ...rest } = quote
71+
return rest
72+
}
73+
6874
const all = {
6975
metadata: {
7076
total: quotes.length,
@@ -86,11 +92,11 @@ for (const quote of all.quotes) {
8692

8793
const authorEntry = authorsWithQuotes.get(quote.author.id)
8894
if (typeof authorEntry !== 'undefined') {
89-
authorEntry.quotes.push(quote)
95+
authorEntry.quotes.push(removeAuthorFromQuote(quote))
9096
} else {
9197
authorsWithQuotes.set(quote.author.id, {
9298
...quote.author,
93-
quotes: [quote]
99+
quotes: [removeAuthorFromQuote(quote)]
94100
})
95101
}
96102

@@ -126,3 +132,15 @@ const allAuthors = {
126132

127133
await writeFile(`${authorsPath}/all.json`, JSON.stringify(allAuthors, null, 2))
128134
console.log(`Written ${authorsPath}/all.json`)
135+
136+
// copy open api file and converts it to json
137+
const openApiPath = join(currentDir, '..', 'src', 'openapi.yml')
138+
const openApiDestYaml = join(destPath, 'openapi.yml')
139+
await copyFile(openApiPath, openApiDestYaml)
140+
console.log(`Written ${openApiDestYaml}`)
141+
142+
const openApiYaml = await readFile(openApiPath, 'utf-8')
143+
const openApiJson = parse(openApiYaml)
144+
const openApiDestJson = join(destPath, 'openapi.json')
145+
await writeFile(openApiDestJson, JSON.stringify(openApiJson, null, 2))
146+
console.log(`Written ${openApiDestJson}`)

‎src/openapi.yml‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
openapi: 3.1.0
2+
3+
info:
4+
title: Tech Quotes API
5+
version: 1.0.0
6+
description: |-
7+
A simple API to get inspiring tech quotes.
8+
9+
Source code on GitHub: https://github.com/FullStackBulletin/tech-quotes
10+
license:
11+
name: MIT
12+
url: https://raw.githubusercontent.com/FullStackBulletin/tech-quotes/main/LICENSE
13+
14+
servers:
15+
- url: https://fullStackbulletin.github.io/tech-quotes
16+
description: GitHub Pages
17+
18+
tags:
19+
- name: quotes
20+
description: Quotes
21+
- name: authors
22+
description: Authors
23+
24+
paths:
25+
/quotes/stats.json:
26+
get:
27+
tags:
28+
- quotes
29+
summary: Get quotes stats
30+
description: Get quotes stats
31+
operationId: getQuotesStats
32+
responses:
33+
"200":
34+
description: OK
35+
content:
36+
application/json:
37+
schema:
38+
$ref: "#/components/schemas/QuotesStats"
39+
/quotes/all.json:
40+
get:
41+
tags:
42+
- quotes
43+
summary: Get all quotes
44+
description: Get all quotes
45+
operationId: getAllQuotes
46+
responses:
47+
"200":
48+
description: OK
49+
content:
50+
application/json:
51+
schema:
52+
$ref: "#/components/schemas/AllQuotes"
53+
/quotes/{quoteId}.json:
54+
get:
55+
tags:
56+
- quotes
57+
summary: Get a single quote by ID
58+
description: Get a single quote by ID
59+
operationId: getQuote
60+
parameters:
61+
- in: path
62+
name: quoteId
63+
schema:
64+
type: integer
65+
required: true
66+
responses:
67+
"200":
68+
description: OK
69+
content:
70+
application/json:
71+
schema:
72+
$ref: "#/components/schemas/Quote"
73+
/authors/stats.json:
74+
get:
75+
tags:
76+
- authors
77+
summary: Get authors stats
78+
description: Get authors stats
79+
operationId: getAuthorsStats
80+
responses:
81+
"200":
82+
description: OK
83+
content:
84+
application/json:
85+
schema:
86+
$ref: "#/components/schemas/AuthorsStats"
87+
/authors/all.json:
88+
get:
89+
tags:
90+
- authors
91+
summary: Get all authors
92+
description: Get all authors
93+
operationId: getAllAuthors
94+
responses:
95+
"200":
96+
description: OK
97+
content:
98+
application/json:
99+
schema:
100+
$ref: "#/components/schemas/AllAuthors"
101+
/authors/{authorId}.json:
102+
get:
103+
tags:
104+
- "authors"
105+
summary: Get a single author by ID
106+
description: Get a single author by ID
107+
operationId: getAuthor
108+
parameters:
109+
- in: path
110+
name: authorId
111+
schema:
112+
type: string
113+
required: true
114+
responses:
115+
"200":
116+
description: OK
117+
content:
118+
application/json:
119+
schema:
120+
$ref: "#/components/schemas/AuthorWithQuotes"
121+
122+
components:
123+
schemas:
124+
QuoteWithoutAuthor:
125+
type: object
126+
properties:
127+
id:
128+
type: integer
129+
description: Quote ID
130+
text:
131+
type: string
132+
description: Quote text
133+
url:
134+
type: string
135+
description: URL to retrieve the quote
136+
Quote:
137+
allOf:
138+
- $ref: "#/components/schemas/QuoteWithoutAuthor"
139+
type: object
140+
properties:
141+
author:
142+
$ref: "#/components/schemas/Author"
143+
Author:
144+
type: object
145+
properties:
146+
id:
147+
type: string
148+
description: Author ID
149+
name:
150+
type: string
151+
description: Author name
152+
description:
153+
type: string
154+
description: Author description
155+
wiki:
156+
type: string
157+
description: URL to Wikipedia page
158+
nullable: true
159+
url:
160+
type: string
161+
description: URL to retrieve author
162+
QuotesStats:
163+
type: object
164+
properties:
165+
total:
166+
type: integer
167+
description: Total number of quotes
168+
all:
169+
type: string
170+
description: URL to retrieve all quotes
171+
first:
172+
type: string
173+
description: URL to retrieve first quote
174+
last:
175+
type: string
176+
description: URL to retrieve last quote
177+
urlPrefix:
178+
type: string
179+
description: URL prefix to retrieve quotes
180+
AllQuotes:
181+
type: object
182+
properties:
183+
metadata:
184+
type: object
185+
properties:
186+
total:
187+
type: integer
188+
description: Total number of quotes
189+
first:
190+
type: integer
191+
description: First id of a quote
192+
last:
193+
type: integer
194+
description: Last id of a quote
195+
quotes:
196+
type: array
197+
items:
198+
$ref: "#/components/schemas/Quote"
199+
description: the list of all quotes
200+
AuthorsStats:
201+
type: object
202+
properties:
203+
total:
204+
type: integer
205+
description: Total number of authors
206+
all:
207+
type: string
208+
description: URL to retrieve all authors
209+
urlPrefix:
210+
type: string
211+
description: URL prefix to retrieve authors
212+
AllAuthors:
213+
type: object
214+
properties:
215+
metadata:
216+
type: object
217+
properties:
218+
total:
219+
type: integer
220+
description: Total number of authors
221+
authors:
222+
type: array
223+
items:
224+
type: string
225+
description: the list of all author IDs
226+
AuthorWithQuotes:
227+
type: object
228+
allOf:
229+
- $ref: "#/components/schemas/Author"
230+
properties:
231+
quotes:
232+
type: array
233+
items:
234+
$ref: "#/components/schemas/QuoteWithoutAuthor"

0 commit comments

Comments
 (0)