ASCOMInitiative / ASCOMRemote

The ASCOM REST based Remote Driver Server and Remote Access Clients
GNU General Public License v3.0
57 stars 15 forks source link

Extract common parts of requests and responses #39

Closed RReverser closed 1 year ago

RReverser commented 1 year ago

This utilises #/components/responses section as well as allOf combinator of OpenAPI v3 to extract common transaction properties (ClientID, ClientTransactionID, ServerTransactionID) and error properties (ErrorNumber and ErrorMessage) from all request and response bodies.

This makes the spec about ~2x shorter and should reduce copy-paste mistakes and typos.

Example before:

put:
  summary: Turns the camera cooler on and off
  description: 'Turns on and off the camera cooler. True = cooler on, False = cooler off'
  tags:
    - Camera Specific Methods
  parameters:
    - $ref: '#/components/parameters/device_number'
  responses:
    '200':
    description: Transaction complete or exception
    content:
      application/json:
      schema:
        $ref: '#/components/schemas/MethodResponse'
    '400':
    description: 'Method or parameter value error, check error message'
    content:
      text/plain:
      schema:
        type: string
        description: Error message describing why the command cannot be processed
    '500':
    description: 'Server internal error, check error message'
    content:
      text/plain:
      schema:
        type: string
        description: Error message describing why the command cannot be processed
  requestBody:
    content:
    application/x-www-form-urlencoded:
      schema:
      type: object
      properties:
        CoolerOn:
        description: Cooler state
        type: boolean
        default: true
        ClientID:
        description: Client's unique ID. (0 to 4294967295). The client should choose a value at start-up, e.g. a random value between 0 and 65535, and send this value on every transaction to help associate entries in device logs with this particular client.
        type: integer
        format: uint32
        ClientTransactionID:
        description: Client's transaction ID. (0 to 4294967295). The client should start this count at 1 and increment by one on each successive transaction. This will aid associating entries in device logs with corresponding entries in client side logs.
        type: integer
        format: uint32
      required:
        - CoolerOn

Example after:

put:
  summary: Turns the camera cooler on and off
  description: 'Turns on and off the camera cooler. True = cooler on, False = cooler off'
  tags:
    - Camera Specific Methods
  parameters:
    - $ref: '#/components/parameters/device_number'
  responses:
    '200':
      $ref: '#/components/responses/MethodResponse'
    '400':
      $ref: '#/components/responses/400'
    '500':
      $ref: '#/components/responses/500'
  requestBody:
    content:
      application/x-www-form-urlencoded:
        schema:
          allOf:
            - $ref: '#/components/schemas/AlpacaRequest'
            - properties:
                CoolerOn:
                  description: Cooler state
                  type: boolean
                  default: true
              required:
                - CoolerOn
RReverser commented 1 year ago

Note: best to review in whitespace-ignoring mode (https://github.com/ASCOMInitiative/ASCOMRemote/pull/39/files?w=1) as my editor trimmed various unnecessary trailing spaces as part of the same change. I could try to revert those if preferable, but there's no point in keeping those spaces anyway.