# HG changeset patch # User Kim Alvefur # Date 1614706554 -3600 # Node ID f877a4d3770b384b2a6f0750ca224eac122683d8 # Parent 4f41678ba00da12363ef30a4f7c499755aca2d77 mod_rest/openapi: Deduplicate things using references diff -r 4f41678ba00d -r f877a4d3770b mod_rest/openapi.yaml --- a/mod_rest/openapi.yaml Tue Mar 02 16:14:20 2021 +0100 +++ b/mod_rest/openapi.yaml Tue Mar 02 18:35:54 2021 +0100 @@ -13,55 +13,29 @@ /rest: post: requestBody: - required: true - content: - application/x-www-form-urlencoded: - schema: - description: A subset of the JSON schema, only top level string fields. - application/xmpp+xml: - schema: - description: Single XMPP stanza in XML format. - application/json: - schema: - $ref: '#/components/schemas/stanza' + $ref: '#/components/requestBodies/common' security: - basic: [] - token: [] summary: Send stanzas and receive responses. Webhooks work the same way. responses: 200: - content: - text/plain: - schema: - description: Plain text response used as message body. - example: Hello - type: string - application/x-www-form-urlencoded: - schema: - description: A subset of the JSON schema, only top level string fields. - example: body=Hello - application/xmpp+xml: - schema: - description: Single XMPP stanza in XML format. - example: Hello - application/json: - schema: - $ref: '#/components/schemas/stanza' - description: The stanza was sent and returned a response. - 401: - description: No credentials or auth token were provided. + $ref: '#/components/responses/success' 202: - description: The stanza was sent without problem, and without response, - so an empty reply. - 403: - description: Provided credentials or token not accepted. - 400: - description: There was a syntax problem in the payload. - 422: - description: The was a problem with the format (but not the syntax) of the - payload. - 415: - description: Unsupported mediatype. + $ref: '#/components/responses/sent' + /rest/{kind}/{type}/{to}: + post: + security: + - basic: [] + - token: [] + summary: Even more RESTful mapping with certain components in the path. + parameters: + - $ref: '#/components/parameters/kind' + - $ref: '#/components/parameters/type' + - $ref: '#/components/parameters/to' + responses: + 200: + $ref: '#/components/responses/success' /rest/ping/{to}: get: security: @@ -70,22 +44,11 @@ summary: Ping a local or remote server or other entity responses: 200: - content: - application/json: - schema: - type: object - application/xmpp+xml: - schema: - description: Single XMPP stanza in XML format. - example: | - - description: OK + $ref: '#/components/responses/success' + 202: + $ref: '#/components/responses/sent' parameters: - - name: to - in: path - required: true - schema: - $ref: '#/components/schemas/to' + - $ref: '#/components/parameters/to' /rest/disco/{to}: get: security: @@ -94,23 +57,9 @@ summary: Query a remote entity for supported features responses: 200: - content: - application/json: - schema: - type: object - properties: - disco: - $ref: '#/components/schemas/disco' - application/xmpp+xml: - schema: - description: See XEP-0030 - description: OK + $ref: '#/components/responses/success' parameters: - - name: to - in: path - required: true - schema: - $ref: '#/components/schemas/to' + - $ref: '#/components/parameters/to' /rest/items/{to}: get: security: @@ -119,77 +68,20 @@ summary: Query an entity for related services, chat rooms or other items responses: 200: - content: - application/json: - schema: - type: object - properties: - disco: - $ref: '#/components/schemas/items' - application/xmpp+xml: - schema: - description: See XEP-0030 - description: OK + $ref: '#/components/responses/success' parameters: - - name: to - in: path - required: true - schema: - $ref: '#/components/schemas/to' + - $ref: '#/components/parameters/to' /rest/version/{to}: get: security: - basic: [] - token: [] - summary: Ask what software version is used + summary: Ask what software version is used. responses: 200: - content: - application/json: - schema: - $ref: '#/components/schemas/stanza' - application/xmpp+xml: - schema: - description: Single XMPP stanza in XML format. - example: | - - - Exodus - 0.7.0.4 - - - description: OK + $ref: '#/components/responses/success' parameters: - - name: to - in: path - required: true - schema: - $ref: '#/components/schemas/to' - /rest/{kind}/{type}/{to}: - post: - responses: - 200: - description: Okay - security: - - basic: [] - - token: [] - summary: Even more RESTful mapping. - parameters: - - name: kind - in: path - required: true - schema: - $ref: '#/components/schemas/kind' - - name: type - in: path - required: true - schema: - $ref: '#/components/schemas/type' - - name: to - in: path - required: true - schema: - $ref: '#/components/schemas/to' + - $ref: '#/components/parameters/to' components: schemas: stanza: @@ -575,4 +467,60 @@ description: Use JID as username. scheme: Basic type: http + requestBodies: + common: + required: true + content: + application/x-www-form-urlencoded: + schema: + description: A subset of the JSON schema, only top level string fields. + application/xmpp+xml: + schema: + description: Single XMPP stanza in XML format. + application/json: + schema: + $ref: '#/components/schemas/stanza' + responses: + success: + description: The stanza was sent and returned a response. + content: + application/json: + schema: + $ref: '#/components/schemas/stanza' + application/xmpp+xml: + schema: + description: Single XMPP stanza in XML format. + example: Hello + application/x-www-form-urlencoded: + schema: + description: A subset of the JSON schema, only top level string fields. + example: body=Hello + text/plain: + schema: + description: Plain text response used as message body. + example: Hello + type: string + sent: + description: The stanza was sent without problem, and without response, + so an empty reply. + parameters: + to: + name: to + in: path + required: true + schema: + $ref: '#/components/schemas/to' + kind: + name: kind + in: path + required: true + schema: + $ref: '#/components/schemas/kind' + type: + name: type + in: path + required: true + schema: + $ref: '#/components/schemas/type' + ...