arjenhiemstra/ithowifi

[Feature] Add OpenApi Spec / SwaggerUI to document api

Opened this issue · 1 comments

Describe the bug
It would be really cool to add an openapi specification to document all the possible options of your web api.

Sample

openapi: 3.0.0
info:
  title: Web API
  version: 1.0.0
paths:
  /api.html:
    get:
      parameters:
        - name: vremotecmd
          in: query
          schema:
            type: string
            enum: ["away", "low", "medium", "high", "timer1", "timer2", "timer3", "join", "leave", "auto", "autonight", "cook30", "cook60"]
        - name: vremoteindex
          in: query
          schema:
            type: string
            pattern: "^[0-11]$"
        - name: vremotename
          in: query
          schema:
            type: string
        - name: username
          in: query
          schema:
            type: string
            maxLength: 20
        - name: password
          in: query
          schema:
            type: string
            maxLength: 20
        - name: clearqueue
          in: query
          schema:
            type: string
            enum: ["true"]
        - name: get
          in: query
          schema:
            type: string
            enum: ["ithostatus"]
        - name: speed
          in: query
          schema:
            type: string
            pattern: "^[0-255]$"
        - name: command
          in: query
          schema:
            type: string
            enum: ["low", "medium", "high", "timer1", "timer2", "timer3", "clearqueue"]
        - name: timer
          in: query
          schema:
            type: string
            pattern: "^[0-65535]$"
        - name: currentspeed
          in: query
          schema:
            type: string
            enum: ["ithostatus"]
      responses:
        '200':
          description: Successful response
          content:
            text/plain:
              example: OK
        '400':
          description: Unsuccessful response
          content:
            text/plain:
              example: NOK
      description: Format the request as http://[DNS or IP]/api.html?[param]=[value]
      summary: Simple Web API

# Add more paths and details as needed for specific commands and functionalities

Expected behaviour
The API page would be an SwaggerUI api describing the API and allowing users to directly test the API from the portal.

Screenshots
image

image

good one! I'm currently working on changing the API response from the OK / NOK that it is now to a reply JSON based with some more info. This could be a change to accompanying that nicely.