Instantly share code, notes, and snippets.
Created
March 3, 2021 01:33
-
Star
(0)
0
You must be signed in to star a gist -
Fork
(0)
0
You must be signed in to fork a gist
-
Save jdretz/7025f496f64cfbe40b9bd3c44df46655 to your computer and use it in GitHub Desktop.
YAML OpenAPI Specification Related Articles API
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.0.0 | |
info: | |
version: 1.0.0 | |
title: Related Articles | |
description: Manage related articles for blog post | |
contact: | |
name: Support | |
email: jretz@jrts.info | |
paths: | |
/article/related/{id}: | |
get: | |
parameters: | |
- name: id | |
in: path | |
description: ID of article | |
required: true | |
schema: | |
type: string | |
example: 20 | |
description: Returns the article ID and the IDs of related articles. | |
responses: | |
'200': | |
description: List of related articles. | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/relatedArticles' | |
examples: | |
success: | |
$ref: '#/components/examples/successWithIds' | |
successNoIds: | |
$ref: '#/components/examples/successWithoutIds' | |
'404': | |
description: Article ID could not be found | |
content: | |
'applications/json': | |
schema: | |
$ref: '#/components/schemas/error' | |
examples: | |
success: | |
$ref: '#/components/examples/error' | |
patch: | |
summary: Updates an article with related article IDs | |
operationId: updateRelatedIds | |
parameters: | |
- name: id | |
in: path | |
description: ID of article that needs to be updated | |
required: true | |
schema: | |
type: string | |
example: 10 | |
requestBody: | |
content: | |
'application/json': | |
schema: | |
type: object | |
properties: | |
ids: | |
description: IDs to add to the list | |
type: array | |
items: | |
type: string | |
example: ['4', '5', '6'] | |
required: | |
- ids | |
examples: | |
patchBody: | |
$ref: '#/components/examples/patchBody' | |
responses: | |
'200': | |
description: Article updated. | |
content: | |
'application/json': | |
schema: | |
type: object | |
items: | |
$ref: '#/components/schemas/relatedArticles' | |
examples: | |
success: | |
$ref: '#/components/examples/patchSuccess' | |
'404': | |
description: Article not found | |
content: | |
'application/json': | |
schema: | |
type: object | |
items: | |
$ref: '#/components/schemas/error' | |
examples: | |
notFound: | |
$ref: '#/components/examples/error' | |
/article/generate: | |
post: | |
summary: Finds related articles and returns the IDs | |
operationId: generateRelatedIds | |
requestBody: | |
content: | |
'application/json': | |
schema: | |
type: object | |
properties: | |
id: | |
description: ID of article | |
type: string | |
example: 20 | |
title: | |
description: Title of article | |
type: string | |
example: Inheritance with Python | |
category: | |
description: Parent category | |
type: string | |
example: tech | |
subCategories: | |
description: Any subcategories of parent | |
type: array | |
items: | |
type: string | |
example: ['Python', 'Building a Python Package'] | |
tags: | |
description: Tags for article | |
type: array | |
items: | |
type: string | |
example: ['api', 'python', 'fastapi'] | |
required: | |
- id | |
- title | |
examples: | |
generateBody: | |
$ref: '#/components/examples/generateBody' | |
responses: | |
'200': | |
description: Found related articles | |
content: | |
'application/json': | |
schema: | |
type: object | |
properties: | |
ids: | |
items: | |
type: string | |
example: ['7', '8', '9'] | |
examples: | |
success: | |
$ref: '#/components/examples/generateSuccess' | |
'404': | |
description: Article not found | |
content: | |
'application/json': | |
schema: | |
type: object | |
items: | |
$ref: '#/components/schemas/error' | |
examples: | |
notFound: | |
$ref: '#/components/examples/error' | |
servers: | |
# Added by API Auto Mocking Plugin | |
- description: SwaggerHub API Auto Mocking | |
url: https://virtserver.swaggerhub.com/jdretz/related-articles/1.0.0 | |
components: | |
schemas: | |
relatedArticles: | |
type: object | |
properties: | |
articleId: | |
type: string | |
related: | |
type: array | |
items: | |
type: string | |
error: | |
type: object | |
properties: | |
detail: | |
type: string | |
description: Error object | |
examples: | |
successWithoutIds: | |
value: | |
articleId: 20 | |
related: [] | |
successWithIds: | |
value: | |
articleId: 10 | |
related: ['1', '2', '3'] | |
error: | |
value: | |
detail: 'Not found.' | |
patchBody: | |
value: | |
ids: ['4', '5', '6'] | |
patchSuccess: | |
value: | |
articleId: 10 | |
related: ['4', '5', '6'] | |
generateSuccess: | |
value: | |
articleId: 20 | |
ids: ['7', '8', '9'] | |
generateBody: | |
value: | |
id: 20 | |
title: Inheritance With Python | |
category: tech | |
subCategories: ['Python', 'Building a Python Package'] | |
tags: [api, python ,fastapi] |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment