Add OpenAPI schema definition

[tiran]

The multiplexer now provides OpenAPI schema for public API endpoints. Starlette's API schema generator uses a mix of introspection and YAML in doc strings. The schema is available under /api/webconsole/v1/schema path and python appservice/multiplexer.py schema on the command line.

The SchemaGenerator introduces a new dependency on pyyaml package.

See: https://www.starlette.io/schemas/

[tiran]

Example output:

$ ./.venv/bin/python appservice/multiplexer.py schema
info:
  title: webconsole
  version: '1.0'
openapi: 3.0.0
paths:
  /api/webconsole/v1/ping:
    get:
      responses:
        200:
          description: Returns pong
      summary: Ping service
  /api/webconsole/v1/sessions/new:
    post:
      response:
        200:
          description: new session
          example: '{"id": "42cdaa42-413a-40fa-b5b5-29c2a8ad8555"}'
        500:
          description: time out
      summary: Create a new session
  /api/webconsole/v1/sessions/{sessionid}/status:
    get:
      response:
        200:
          description: session status (running, closed, wait_target)
        404:
          description: unknown session id
      summary: Get session status
  /api/webconsole/v1/sessions/{sessionid}/wait-running:
    get:
      response:
        200:
          description: session is running
        404:
          description: unknown session id
      summary: Wait for session
  /wss/webconsole/v1/sessions/{sessionid}/web/{path}:
    get:
      response:
        200:
          description: success
        404:
          description: unknown session id
      summary: reverse-proxy cockpit HTTP to session pod

[marusak]

  /wss/webconsole/v1/sessions/{sessionid}/web/{path}:
    get:
      response:
        200:
          description: success
        404:
          description: unknown session id
      summary: reverse-proxy cockpit HTTP to session pod

This is a bit weird, we have wss://console.redhat.com/wss/webconsole/v1/sessions/<session_id>/ws and https://console.redhat.com/wss/webconsole/v1/sessions/<session_id>/web endpoints. The ws is missing and the web is defined with path which is not really the way it is defined as endpoint.