I'm currently working on a Redfish compliant API for our Network Manager product. We are using standard redfish resources and extending them through the OEM property. We've used the provided DMTF tools on github to generated the json and openapi docs from our CSDL. My questions are around the openapi docs.
1) How are we supposed to advertise our custom oem extensions objects from the base openapi.yaml file? It will have responses that reference the core types (NetworkAdapter in our case) but the NetworkAdapter schema file will not reference our custom oem extension even though it will be part of the response. What's the intended workflow for a client to go from the openapi.yaml file to get to the oem extension?
2) If we would like to host the openapi schema files on the server itself and not statically from a website, is there a standard convention as to which URL we should host them under? I know that the main openapi doc should be under /redfish/v1/openapi.yaml but what about all the supporting docs for the objects referenced in that file?
For your first question, you're allowed to modify standard schemas yourself (in certain manners called out in the spec) to highlight what your service supports. OEM extensions can be inserted in the OpenAPI files. Unfortunately at this time it's a manual process to do this. Generally schema driven clients would scan a service and build the data model for their service ahead of time, so they'd start with the openapi.yaml file, follow the paths, references, and other material to build their structures for interacting with the service. Keep in mind, many clients are not schema driven; other clients might just follow URIs and inspect resources for the properties they care about.
For your second question, part of the schema modification rules is we allow a service to modify the reference URIs to other schema files so that you can point to locally stored schemas. Currently we recommend these local schema files to be found at "/redfish/v1/Schemas/<SchemaFile>".