HF API OpenAPI Definition
Working on your OpenAPI Definition
Install
- Install Node JS.
- Clone this repo and run
npm install
in the repo root.
Usage
npm start
Starts the swagger ui preview server.
npm run build
Bundles the definition to the dist folder.
npm test
Validates the definition.
Documentation Progress
✔️ Documented (Request schema, examples, and response)
❌ Undocumented
Read
✔️ me
✔️ forums
✔️ threads
✔️ posts
✔️ users
✔️ bytes
✔️ contracts
✔️ disputes
✔️ bratings
Write
✔️ posts
✔️ threads
✔️ bytes
✔️ bytes (deposit)
✔️ bytes (withdraw)
✔️ bytes (dump)
❌ contracts
❌ contracts (undo)
❌ contracts (deny)
❌ contracts (approve)
❌ contracts (deny middleman)
❌ contracts (approve middleman)
❌ contracts (cancel vendor contract)
❌ contracts (request cancellation)
❌ contracts (mark complete)
❌ sigmarket (purchase)
❌ sigmarket (sell)
❌ sigmarket (remove signature from signature market)
❌ sigmarket (update purchased signature)
Schemas
Adding Schemas
- Navigate to the
openapi/components/schemas
folder. - Add a file named as you wish to name the schema.
- Define the schema.
- Refer to the schema using the
$ref
(see example below).
Example Paths & Components
A simple path example can be found below. Notice it includes a summary, description, request body, an example, and a sample response.
post:
tags:
- me
summary: Returns information for the current user.
description: Returns information for the current user.
requestBody:
required: true
content:
application/json:
examples:
usernameUsergroup:
summary: return current user's uid, username, and usergroup
value:
asks:
me:
uid: true
username: true
usergroup: true
schema:
$ref: ..\components\schemas\me\MeReadRequestAsk.yaml
responses:
"200":
description: Me info
headers:
x-rate-limit-remaining:
schema:
type: integer
description: Request limit per hour.
content:
application/json:
schema:
$ref: '..\components\schemas\me\MeReadResponse.yaml'
"401":
$ref: ..\components\responses\UnauthorizedError.yaml
$ref
Using the Notice in the path example above the schema definition itself has $ref
links to other schemas defined.
Here is a small excerpt with an example:
content:
application/json:
schema:
$ref: '..\components\schemas\me\MeReadResponse.yaml'
The value of the $ref
is the path to the response schema definition.
You may use $ref
s to compose schema from other existing schema to avoid duplication.
You will use $ref
s to reference schema from your path definitions.
Adding a Path
- Navigate to the
openapi/paths
folder. - Add a new YAML file named like your URL endpoint except replacing
/
with@
and putting path parameters into curly braces like{example}
. - Add the path and a ref to it inside of your
openapi.yaml
file inside of theopenapi
folder.
Example addition to the openapi.yaml
file:
'/customers/{id}':
$ref: './paths/customers@{id}.yaml'