Post by johannes on Nov 14, 2023 10:25:48 GMT
Hi,
i am working on a Redfish API for PowerEquipment. I really want to document this protocol with the provided openapi.yaml file from redfish. And this should be really the only source of documentation for our users. I don't like to maintain additional PDF-documents and such.
So in the past i just pruned the openapi-file of the not used endpoints and HTTP-methodes. On the other side i provided GET examples, so that users can see, what a device could answer. For PATCH requests I specifically designed the examples of the request bodys so that they only show properties, which are changable by the user. Especially in the SwaggerUI this is usefull in my oppinion.
For users who are familiar mit redfish, this should be enough. Linked redfish-schemata and the pdf redfish-specification, available at dmtf, will describe all the rest. But we also have users which come from our SNMP implementation and want to use the new API or just requested some type of RestAPI. They might not want to read throug the whole redfish doc and study the schemata for each ressource just to understand some properties. For example a UserLabel for PDU outlets is named "description" on our WebUI and SNMP.
For now i have two ideas for these customers.
For now i have two ideas for these customers.
1. I could add a markdown table in the openapi:
2. Or a bit more involved, could copy the redfish schema and edit the description for each property to gives this information. Maybe even build my own JSON-Schema without directing to DMTF.
As an example i pruned the schema of the outlet to only show a few properties:
Especially with 2 i am not shure, if i can just provide a customized redfish schema. For now we only provide the openapi at our devices and all the links for the schemata direct to the dmtf server. Users without internet or just restricted access to it might not be able to access schema definitions.
1:
+ easy to understand for users of different Protocols (WebUI, SNMP, ...)
+ easy to create
- some double info in tabel and redfish-schema
- not readable my machines
2:
+ doc would be available in standard openapi form
+ doc would be available in standard openapi form
+ doc would be available offline
+ no double info in tabel and schema
+ no double info in tabel and schema
- a lot of work to edit all schemata and provide them at the same source as the openapi.yaml
So, what would be the desired way of providing this information? Are there other reasonable solutions to this problem beside my two approaches?
best regards
Johannes
best regards
Johannes
