OpenAPI Description Document for the JSON statistics channel
Description
Using the JSON statistics channel is easier when parsing of the data is accomplished using a description document.
Request
I prepared the following description document - it validates and works.
Possible improvements include:
- not using additionalProperties: { type: integer } for the statistics,
- document the statistic values (#3878)
- require properties
Would be great if you could include this next to https://gitlab.isc.org/isc-projects/bind9/-/blob/main/bin/named/bind9.xsl and have the webserver serve it as bind9.yaml similar to https://gitlab.isc.org/isc-projects/bind9/-/blob/main/bin/named/statschannel.c#L3138 for ease of use.
Links / references
As I'm unable to fork the repo and create a MR (project limit reached), it is embedded inline.
openapi: "3.0.0"
info:
version: "0.1"
title: OpenAPI Description Document for Bind9 JSON statistics channel
servers:
- url: /
paths:
/json:
get:
operationId: summary
responses:
'200':
description: The Summary
content:
application/json:
schema:
$ref: "#/components/schemas/Summary"
/json/v1/status:
# /json/v1:
get:
operationId: status
responses:
'200':
description: The Status
content:
application/json:
schema:
$ref: "#/components/schemas/Status"
/json/v1/server:
get:
operationId: server
responses:
'200':
description: The Status
content:
application/json:
schema:
$ref: "#/components/schemas/Server"
/json/v1/zones:
get:
operationId: zones
responses:
'200':
description: The Zones
content:
application/json:
schema:
$ref: "#/components/schemas/Views"
/json/v1/net:
get:
operationId: net
responses:
'200':
description: The Sockstats
content:
application/json:
schema:
$ref: "#/components/schemas/Sockstats"
/json/v1/mem:
get:
operationId: mem
responses:
'200':
description: The Memory Statistics
content:
application/json:
schema:
$ref: "#/components/schemas/Memory"
/json/v1/traffic:
get:
operationId: traffic
responses:
'200':
description: The Traffic Statistics
content:
application/json:
schema:
$ref: "#/components/schemas/Traffic"
components:
schemas:
Status:
type: object
additionalProperties: False
properties:
json-stats-version:
type: string
boot-time:
type: string
format: date-time
config-time:
type: string
format: date-time
current-time:
type: string
format: date-time
version:
type: string
Server:
type: object
additionalProperties: False
allOf:
- $ref: "#/components/schemas/Status"
- $ref: "#/components/schemas/Views"
properties:
opcodes:
type: object
additionalProperties:
type: integer
rcodes:
type: object
additionalProperties:
type: integer
qtypes:
type: object
additionalProperties:
type: integer
nsstats:
type: object
additionalProperties:
type: integer
zonestats:
type: object
additionalProperties:
type: integer
Views:
type: object
additionalProperties: False
allOf:
- $ref: "#/components/schemas/Status"
properties:
views:
type: object
additionalProperties:
$ref: "#/components/schemas/View"
View:
type: object
additionalProperties: False
properties:
zones:
type: array
items:
$ref: "#/components/schemas/Zone"
resolver:
type: object
additionalProperties: False
properties:
stats:
type: object
additionalProperties:
type: integer
qtypes:
type: object
additionalProperties:
type: integer
cache:
type: object
additionalProperties:
type: integer
cachestats:
type: object
additionalProperties:
type: integer
adb:
type: object
additionalProperties:
type: integer
Zone:
type: object
additionalProperties: False
properties:
name:
type: string
class:
type: string
serial:
type: integer
type:
type: string
loaded:
type: string
Sockstats:
type: object
additionalProperties: False
allOf:
- $ref: "#/components/schemas/Status"
properties:
sockstats:
type: object
additionalProperties:
type: integer
Memory:
type: object
additionalProperties: False
allOf:
- $ref: "#/components/schemas/Status"
properties:
memory:
type: object
additionalProperties: False
properties:
TotalUse:
type: integer
InUse:
type: integer
Malloced:
type: integer
ContextSize:
type: integer
Lost:
type: integer
contexts:
type: array
items:
$ref: "#/components/schemas/MemoryContext"
MemoryContext:
type: object
additionalProperties: False
properties:
id:
type: string
name:
type: string
references:
type: integer
total:
type: integer
inuse:
type: integer
maxinuse:
type: integer
malloced:
type: integer
maxmalloced:
type: integer
pools:
type: integer
hiwater:
type: integer
lowater:
type: integer
Traffic:
type: object
additionalProperties: False
allOf:
- $ref: "#/components/schemas/Status"
properties:
traffic:
type: object
additionalProperties:
$ref: "#/components/schemas/TrafficData"
TrafficData:
type: object
additionalProperties:
type: integer
TaskMgr:
type: object
additionalProperties: False
properties:
taskmgr:
type: object
additionalProperties: False
properties:
thread-model:
type: string
default-quantum:
type: integer
tasks:
type: array
items:
$ref: "#/components/schemas/Task"
Task:
type: object
additionalProperties: False
properties:
id:
type: string
name:
type: string
references:
type: integer
state:
type: string
quantum:
type: integer
events:
type: integer
Summary:
type: object
additionalProperties: False
allOf:
- $ref: "#/components/schemas/Status"
- $ref: "#/components/schemas/Server"
- $ref: "#/components/schemas/Views"
- $ref: "#/components/schemas/Memory"
- $ref: "#/components/schemas/Sockstats"
- $ref: "#/components/schemas/Traffic"
- $ref: "#/components/schemas/TaskMgr"