Skip to content

Instantly share code, notes, and snippets.

@vhood

vhood/json-api-open-api.yml

Last active April 5, 2024 19:09
Show Gist options
  • Save vhood/f9bde1e465ea4dce1a49d8092150aa4c to your computer and use it in GitHub Desktop.
Save vhood/f9bde1e465ea4dce1a49d8092150aa4c to your computer and use it in GitHub Desktop.
Download ZIP
JSON:API swagger (OpenAPI) example
Raw
json-api-open-api.yml
openapi: 3.0.3
info:
title: JSON:API
version: 1.1.0
description: |
This is an example of [JSON:API](https://jsonapi.org) specification
according to OpenAPI documentation
paths:
/posts:
get:
description: Get posts
tags:
- Fetching data
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/Posts'
'default':
description: Error
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts
errors:
$ref: '#/components/schemas/ForbiddenError'
post:
description: Create new post
tags:
- Creating, Updating and Deleting
parameters:
- name: data
required: true
in: query
description: New posts
schema:
type: array
items:
type: object
example:
- data:
- type: posts
attributes:
title: New post title
text: New post text
author_id: 123
responses:
'201':
description: Success
headers:
Location:
schema:
type: string
description: Link to created post
content:
application/vnd.api+json:
schema:
type: object
required:
- jsonapi
- links
- data
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts
data:
allOf:
- $ref: '#/components/schemas/Post'
- type: object
properties:
id:
type: integer
example: 2
attributes:
type: object
properties:
id:
type: integer
example: 2
title:
type: string
example: New post title
text:
type: string
example: New post text
author_id:
type: integer
example: 123
'default':
description: Error
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts
errors:
$ref: '#/components/schemas/ForbiddenError'
/posts/{id}:
get:
description: Get post by id
tags:
- Fetching data
parameters:
- name: id
required: true
in: path
description: post id
schema:
type: string
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/1
data:
$ref: '#/components/schemas/Post'
'default':
description: Error
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/1
errors:
$ref: '#/components/schemas/ForbiddenError'
patch:
description: Update the post
tags:
- Creating, Updating and Deleting
parameters:
- name: id
required: true
in: path
description: post id
schema:
type: string
- name: data
required: true
in: query
description: New post data
schema:
type: array
items:
type: object
example:
- data:
- type: posts
id: 1
attributes:
text: Lorem Ipsum 2 coming soon!
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
type: object
required:
- jsonapi
- links
- data
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/1
data:
allOf:
- $ref: '#/components/schemas/Post'
- type: object
properties:
attributes:
type: object
properties:
id:
type: integer
example: 2
title:
type: string
example: New post title
text:
type: string
example: Lorem Ipsum 2 coming soon!
author_id:
type: integer
example: 123
'default':
description: Error
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/1
errors:
$ref: '#/components/schemas/ForbiddenError'
delete:
description: Delete the post
tags:
- Creating, Updating and Deleting
parameters:
- name: id
required: true
in: path
description: post id
schema:
type: string
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
type: object
required:
- jsonapi
- links
- data
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/1
'default':
description: Error
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/1
errors:
$ref: '#/components/schemas/ForbiddenError'
/posts/{id}/relationships/author:
get:
description: Get post author
tags:
- Fetching data
parameters:
- name: id
required: true
in: path
description: post id
schema:
type: string
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/User'
'default':
description: Error
content:
application/vnd.api+json:
schema:
type: object
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts/{id}/relationships/author
errors:
$ref: '#/components/schemas/ForbiddenError'
components:
schemas:
Posts:
type: object
required:
- jsonapi
- links
- data
properties:
jsonapi:
type: object
properties:
version:
type: string
example: 1.1
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/posts?page[offset]=20&page[limit]=10
pagination:
type: object
properties:
first:
type: string
example: https://example.com/api/v1/posts
last:
type: string
example: https://example.com/api/v1/posts?page[offset]=90&page[limit]=10
prev:
type: string
example: https://example.com/api/v1/posts?page[offset]=10&page[limit]=10
next:
type: string
example: https://example.com/api/v1/posts?page[offset]=30&page[limit]=10
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/Post'
- type: object
properties:
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/post/1
Post:
type: object
required:
- type
- id
- attributes
properties:
type:
type: string
example: posts
id:
type: integer
example: 1
attributes:
type: object
required:
- id
- title
- text
- author_id
properties:
id:
type: integer
example: 1
title:
type: string
example: First blog title
text:
type: string
example: Lorem Ipsum dolor sit amet!
author_id:
type: integer
example: 123
created_at:
type: string
example: 2020-20-02 11:11:11
updated_at:
type: string
example: 2020-20-02 11:11:11
relationships:
type: object
properties:
author:
type: object
properties:
links:
type: object
properties:
self:
type: string
example: https://example.com/api/v1/post/1/relationships/author
related:
type: string
example: https://example.com/api/v1/users/123
User:
type: object
required:
- type
- id
- attributes
properties:
type:
type: string
example: users
id:
type: integer
example: 123
attributes:
type: object
required:
- id
- name
properties:
id:
type: integer
example: 123
name:
type: string
example: User name
created_at:
type: string
example: 2020-02-02 11:11:11
updated_at:
type: string
example: 2020-02-02 11:11:11
ForbiddenError:
type: object
required:
- status
- title
- detail
properties:
status:
type: integer
example: 403
title:
type: string
example: Access denied
detail:
type: string
example: You are not allowed to perform this action
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment