Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature] Add OpenApi Spec / SwaggerUI to document api #214

Open
galadril opened this issue Nov 9, 2023 · 2 comments
Open

[Feature] Add OpenApi Spec / SwaggerUI to document api #214

galadril opened this issue Nov 9, 2023 · 2 comments
Labels
feature request Request for change or new feature pinned Pinned

Comments

@galadril
Copy link

galadril commented Nov 9, 2023

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

@arjenhiemstra arjenhiemstra added pinned Pinned feature request Request for change or new feature labels Nov 10, 2023
@arjenhiemstra
Copy link
Owner

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.

@galadril
Copy link
Author

galadril commented Sep 5, 2024

This is a sample on how we could add a test api link on the api documentation page.
And load swaggerUI with the openapi spec file of the api so people have a api developer portal
#268

image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature request Request for change or new feature pinned Pinned
Projects
None yet
Development

No branches or pull requests

2 participants