Skip to content

M
mybee
Commit a1175610 authored by Janoš Guljaš's avatar Janoš Guljaš Committed by GitHub
Browse files
Options

update openapi specifications (#624) 

Co-authored-by: default avatarMetacertain <metacertain@gmail.com>
parent 082629c3
Hide whitespace changes
Inline Side-by-side
Showing with 343 additions and 98 deletions
openapi/Swarm.yaml
View file @ a1175610
......@@ -30,13 +30,32 @@ servers:
port:
default: 8080
description: Service port provided in bee node config
paths:
'/bytes':
post:
summary: 'Upload data'
tags:
- 'Endpoints on local bee node'
tags:
- Bytes
parameters:
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
type: boolean
required: false
description: Represents the pinning state of the bytes
- in: header
name: swarm-encrypt
schema:
type: boolean
required: false
description: Represents the encrypting state of the bytes
requestBody:
content:
application/octet-stream:
......@@ -58,8 +77,8 @@ paths:
'/bytes/{reference}':
get:
summary: 'Get referenced data'
tags:
- 'Endpoints on local bee node'
tags:
- Bytes
parameters:
- in: path
name: reference
......@@ -83,26 +102,26 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/chunks/{reference}':
get:
summary: 'Get Chunk'
tags:
- 'Endpoints on local bee node'
tags:
- Chunk
parameters:
- in: path
name: reference
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference'
required: true
description: Swarm address of chunk
description: Swarm address of chunk
responses:
'200':
description: Retrieved chunk content
content:
application/octet-stream:
schema:
type: string
type: string
format: binary
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
......@@ -114,15 +133,15 @@ paths:
description: Default response
post:
summary: 'Upload Chunk'
tags:
- 'Endpoints on local bee node'
tags:
- Chunk
parameters:
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Uid of chunk
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
......@@ -134,7 +153,7 @@ paths:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference'
required: true
description: Swarm address of chunk
description: Swarm address of chunk
requestBody:
content:
application/octet-stream:
......@@ -158,8 +177,8 @@ paths:
'/files':
post:
summary: 'Upload file'
tags:
- 'Endpoints on local bee node'
tags:
- File
parameters:
- in: query
name: name
......@@ -167,6 +186,24 @@ paths:
$ref: 'SwarmCommon.yaml#/components/schemas/FileName'
required: false
description: Filename
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
type: boolean
required: false
description: Represents the pinning state of the file
- in: header
name: swarm-encrypt
schema:
type: boolean
required: false
description: Represents the encrypting state of the file
requestBody:
content:
multipart/form-data:
......@@ -198,8 +235,8 @@ paths:
'/files/{reference}':
get:
summary: 'Get referenced file'
tags:
- 'Endpoints on local bee node'
tags:
- File
parameters:
- in: path
name: reference
......@@ -215,7 +252,7 @@ paths:
schema:
type: string
format: binary
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
......@@ -224,3 +261,192 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/dirs':
post:
summary: 'Upload a collection'
tags:
- Collection
parameters:
- in: header
name: swarm-tag-uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: false
description: Associate upload with an existing Tag UID
- in: header
name: swarm-pin
schema:
type: boolean
required: false
description: Represents the pinning state of the collection
- in: header
name: swarm-encrypt
schema:
type: boolean
required: false
description: Represents the encrypting state of the collection
requestBody:
content:
application/x-tar:
schema:
type: string
format: binary
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/ReferenceResponse'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/bzz/{reference}/{path}':
get:
summary: 'Get referenced file from a collection of files'
tags:
- Collection
parameters:
- in: path
name: reference
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmReference'
required: true
description: Swarm address of content
- in: path
name: path
schema:
type: string
required: true
description: Path to the file in the collection.
- in: query
name: targets
schema:
type: string
required: false
description: Global pinning targets prefix
responses:
'200':
description: Ok
content:
application/octet-stream:
schema:
type: string
format: binary
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/tags':
post:
summary: 'Create Tag'
tags:
- Tag
parameters:
- in: query
name: name
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/TagName'
required: true
description: Tagname
responses:
'200':
description: New Tag Info
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/tags/{uid}':
get:
summary: 'Get Tag information using Uid'
tags:
- Tag
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
responses:
'200':
description: Tag info
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
delete:
summary: 'Delete Tag information using Uid'
tags:
- Tag
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
responses:
'204':
$ref: 'SwarmCommon.yaml#/components/responses/204'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
patch:
summary: 'Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid'
tags:
- Tag
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
requestBody:
description: Can contain swarm hash to use for the tag
required: false
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Address'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Status'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
\ No newline at end of file
openapi/SwarmCommon.yaml
View file @ a1175610
......@@ -36,7 +36,7 @@ components:
$ref: '#/components/schemas/SwarmAddress'
balance:
type: integer
Balances:
type: object
properties:
......@@ -44,7 +44,7 @@ components:
type: array
items:
$ref: '#/components/schemas/Balance'
BzzChunksPinned:
type: object
properties:
......@@ -94,7 +94,7 @@ components:
example: "2020-06-11T11:26:42.6969797+02:00"
Duration:
description: Go time.Duration format
description: Go time.Duration format
type: string
example: "5.0018ms"
......@@ -106,10 +106,10 @@ components:
properties:
hash:
$ref: '#/components/schemas/SwarmAddress'
MultiAddress:
type: string
NewTagResponse:
type: object
properties:
......@@ -135,11 +135,11 @@ components:
type: string
startedAt:
$ref: '#/components/schemas/DateTime'
P2PUnderlay:
type: string
example: "/ip4/127.0.0.1/tcp/7070/p2p/16Uiu2HAmTm17toLDaPYzRyjKn27iCB76yjKnJ5DjQXneFmifFvaX"
Peers:
type: object
properties:
......@@ -158,7 +158,7 @@ components:
ProblemDetails:
type: string
ReferenceResponse:
type: object
properties:
......@@ -189,7 +189,7 @@ components:
type: string
pattern: '^[A-Fa-f0-9]{64}$'
example: "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
SwarmEncryptedReference:
type: string
pattern: '^[A-Fa-f0-9]{128}$'
......@@ -206,7 +206,16 @@ components:
Uid:
type: integer
WelcomeMessage:
type: object
properties:
welcome_message:
type: string
responses:
'204':
description: The resource was deleted successfully.
'400':
description: Bad request
content:
......@@ -225,5 +234,5 @@ components:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
openapi/SwarmDebug.yaml
View file @ a1175610
......@@ -23,12 +23,12 @@ servers:
default: 6060
description: Service port provided in bee node config
paths:
paths:
'/addresses':
get:
summary: Get overlay and underlay addresses of the node
tags:
- Swarm Debug Endpoints
- Connectivity
responses:
'200':
description: Own node underlay and overlay addresses
......@@ -45,7 +45,7 @@ paths:
get:
summary: Get the balances with all known peers
tags:
- Swarm Debug Endpoints
- Balance
responses:
'200':
description: Own balances with all known peers
......@@ -62,7 +62,7 @@ paths:
get:
summary: Get the balances with a specific peer
tags:
- Swarm Debug Endpoints
- Balance
parameters:
- in: path
name: address
......@@ -88,14 +88,14 @@ paths:
get:
summary: Check if chunk at address exists locally
tags:
- Swarm Debug Endpoints
- Chunk
parameters:
- in: path
name: address
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true
description: Swarm address of chunk
description: Swarm address of chunk
responses:
'200':
description: Chunk exists
......@@ -109,7 +109,31 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/404'
default:
description: Default response
delete:
summary: Delete a chunk from local storage
tags:
- Chunk
parameters:
- in: path
name: address
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true
description: Swarm address of chunk
responses:
'200':
description: Chunk exists
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Response'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'404':
$ref: 'SwarmCommon.yaml#/components/responses/404'
default:
description: Default response
'/chunks-pin/{address}':
parameters:
- in: path
......@@ -117,11 +141,11 @@ paths:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true
description: Swarm address of chunk
description: Swarm address of chunk
post:
summary: Pin chunk with given address
tags:
- Swarm Debug Endpoints
- Chunk pinning
responses:
'200':
description: Pinning chunk with address
......@@ -138,7 +162,7 @@ paths:
delete:
summary: Unpin chunk with given address
tags:
- Swarm Debug Endpoints
- Chunk pinning
responses:
'200':
description: Unpinning chunk with address
......@@ -155,7 +179,7 @@ paths:
get:
summary: Get pinning status of chunk with given address
tags:
- Swarm Debug Endpoints
- Chunk pinning
responses:
'200':
description: Pinning state of chunk with address
......@@ -167,12 +191,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/chunks-pin/':
get:
summary: Get list of pinned chunks
tags:
- Swarm Debug Endpoints
- Chunk pinning
responses:
'200':
description: List of pinned chunks
......@@ -184,12 +208,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/connect/{multiAddress}':
post:
summary: Connect to address
tags:
- Swarm Debug Endpoints
- Connectivity
parameters:
- in: path
allowReserved: true
......@@ -216,7 +240,7 @@ paths:
get:
summary: Get health of node
tags:
- Swarm Debug Endpoints
- Status
responses:
'200':
description: Health State of node
......@@ -226,12 +250,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/schemas/Status'
default:
description: Default response
'/peers':
get:
summary: Get a list of peers
tags:
- Swarm Debug Endpoints
- Connectivity
responses:
'200':
description: Returns overlay addresses of connected peers
......@@ -246,14 +270,14 @@ paths:
delete:
summary: Remove peer
tags:
- Swarm Debug Endpoints
- Connectivity
parameters:
- in: path
name: address
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/SwarmAddress'
required: true
description: Swarm address of peer
description: Swarm address of peer
responses:
'200':
description: Disconnected peer
......@@ -267,12 +291,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/pingpong/{peer-id}':
post:
summary: Try connection to node
tags:
- Swarm Debug Endpoints
- Connectivity
parameters:
- in: path
name: peer-id
......@@ -295,13 +319,12 @@ paths:
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/readiness':
get:
summary: Get readiness state of node
tags:
- Swarm Debug Endpoints
- Status
responses:
'200':
description: Health State of node
......@@ -311,68 +334,55 @@ paths:
$ref: 'SwarmCommon.yaml#/components/schemas/Status'
default:
description: Default response
'/tags':
post:
summary: 'Create Tag'
tags:
- Swarm Debug Endpoints
parameters:
- in: query
name: name
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/TagName'
required: true
description: Tagname
'/topology':
get:
description: Get topology of known network
tags:
- Connectivity
responses:
'200':
description: New Tag Info
description: Swarm topology of the bee node
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
$ref: 'SwarmCommon.yaml#/components/schemas/BzzTopology'
'/tags/{uid}':
'/welcome-message':
get:
summary: 'Get Tag information using Uid'
tags:
- Swarm Debug Endpoints
parameters:
- in: path
name: uid
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/Uid'
required: true
description: Uid
summary: Get configured P2P welcome message
tags:
- Connectivity
responses:
'200':
description: Tag info
description: Welcome message
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/NewTagResponse'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
$ref: 'SwarmCommon.yaml#/components/schemas/WelcomeMessage'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
'/topology':
get:
description: Get topology of known network
post:
summary: Set P2P welcome message
tags:
- Swarm Debug Endpoints
- Connectivity
requestBody:
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/WelcomeMessage'
responses:
'200':
description: Swarm topology of the bee node
description: OK
content:
application/json:
schema:
$ref: 'SwarmCommon.yaml#/components/schemas/BzzTopology'
$ref: 'SwarmCommon.yaml#/components/schemas/Status'
'400':
$ref: 'SwarmCommon.yaml#/components/responses/400'
'500':
$ref: 'SwarmCommon.yaml#/components/responses/500'
default:
description: Default response
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment