search

influxdata / openapi

An OpenAPI specification for influx (cloud/oss) apis.
MIT License
17 stars 10 forks source link

docs: fix script description #604

Open jstirnaman opened 1 year ago

jstirnaman commented 1 year ago 
    ```suggestion
  In the request body, provide the script properties to update.

This is my new pattern. Eventually, I plan to append an statement (with redoc-cli) that introduces the properties that can be set, like in YouTube docs--"You can set the following properties for this resource:"

_Originally posted by @jstirnaman in https://github.com/influxdata/openapi/pull/444#discussion_r1014518695_
EstherChristopher commented 1 year ago

Hi @jstirnaman, I'd like to work on this issue if you can show me where it's located and provide context.

jstirnaman commented 1 year ago

Hi, @EstherChristopher. I apologize for the delay. First, I'll answer your question and then offer some context and other areas for contributing.

My suggested change was for the requestBody.description in https://github.com/influxdata/openapi/blob/master/src/svc/invocable-scripts/paths/scripts_scriptID.yml. You can see it in the PR at https://github.com/influxdata/openapi/pull/444/files/c230ca4753795eaf8a28bb1e0eb001f2dae20407#diff-220c65af49b6a48834c420b8c7074a280a430746fa213f049487fd62a6d9217d.

The same change could also apply to any operation that accepts a JSON object in the requestBody.

Regarding the following enhancement idea:

Eventually, I plan to append an statement (with redoc-cli) that introduces the properties that can be set, like in YouTube docs--"You can set the following properties for this resource:"

That would more likely be implemented as an API docs decorator for reference documentation display, i.e. more of a "theming" change for presentation.

Finally, the recent shift toward InfluxDB IOx will change how developers depend on the InfluxDB REST API. /buckets and /authorizations will likely continue to be the most relevant endpoints. If you're looking for API docs and front-end experience (I peeked at your profile), they would benefit from examples and code samples.

EstherChristopher commented 1 year ago

Hi @jstirnaman, I understand the first part of your explanation. However, I don't understand what the other part seems to be talking about. The part on enhancement idea. Other than that, so how do I get started?