Document API

[thebinarypenguin]

Consider using

1. A Postman collection to generate documentation (this is preferred if it doesn't require too much hoop-jumping)

2. An Open API Spec to generate documentation

3. Manually writing documentation (yuck!)

[thebinarypenguin]

Here's an Open API Spec

openapi: 3.0.0
info:
  title: Guinea Pig Server
  description: Sample API server for testing cloud platforms
  version: 1.0.0
paths:

  /:

    get:
      summary: 'Get server information'
      description: >-
        Get some basic information about the server.
      operationId: 'getServerInfo'
      responses:
        200:
          description: 'Server Info'

  /status:

    get:
      summary: 'Check if the server is running'
      description: >-
        Designed to be periodically "pinged" in order to determine if the server 
        is running. It's better to use this endpoint rather than `/` because it 
        returns an empty body and therefore uses less bandwidth.
      operationId: 'checkServerStatus'
      responses:
        200:
          description: 'Empty Body'

  /counter:

    get:
      summary: 'Get counter value'
      description: >-
        Get the counter's current value.
      operationId: 'getCounterValue'
      responses:
        200:
          description: 'Counter State'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterState'

    put:
      summary: 'Update counter value'
      description: >-
        Increment or decrement the counter's value by `step` amount. A positive 
        `step` value increments the counter and a negative `step` value 
        decrements the counter.
      operationId: 'updateCounterValue'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CounterUpdatePayload'
      responses:
        200:
          description: 'Counter State'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CounterState'

  /crash:

    post:
      summary: 'Crash the server'
      description: >-
        Cause the server process to exit with error code 187.
      operationId: 'crashServer'
      responses:
        default:
          description: 'Generic Error'

components:

  schemas:

    CounterState:
      required:
        - value
      properties:
        value:
          type: integer

    CounterUpdatePayload:
      required:
        - step
      properties:
        step:
          type: integer