|
|
Post by jokyjang on Jul 13, 2023 22:05:54 GMT
Hi,
It failed with error missing OpenAPI input!. I suspect the yaml file is not valid for the generator to parse, so I looked into the file and found some paths are in below format. This is definitely not a standard yaml format. What are these paths, and how to get it right for the generator to correctly parse the file? Thanks.
? /redfish/v1/Chassis/{ChassisId}/NetworkAdapters/{NetworkAdapterId}/NetworkDeviceFunctions/{NetworkDeviceFunctionId}/AllowDeny : get: |
|
|
|
Post by mraineri on Jul 13, 2023 23:10:43 GMT
To be honest, we've never been successful at running the OpenAPI codegen process. We've hit a lot of issues with referencing definitions hosted on external sites. Ideally we want the toolchain to be directed to the root "openapi.yaml" file (which is included in each DSP8010 bundle), but from traces we've seen so far any time it follows one of the $refs, it doesn't seem to actually go off and download the file. We've done some testing (see redfishforum.com/thread/342/openapi-generator-errors-redfish-schema) where we've replaced all external $ref instances with pointers to local files and have some success. That said, we haven't tested this in a while to see if the OpenAPI community has made any progress on the tools to help with externally sourced schemas. At least as far as the yaml files go, those patterns starting with "?" have confused folks, but it is indeed a valid yaml format. Some yaml encoders (the one we're using is PyYAML pypi.org/project/PyYAML/) does some of the more comprehensive encoding for long strings like that. This is a "complex mapping key" defined in the YAML spec: yaml.org/spec/1.2.2/ |
|
|
|
Post by jokyjang on Jul 20, 2023 1:15:15 GMT
Thanks for the reply in detail. Yes we did try trimming the openapi swagger file and it runs successfully. However, I just saw another issue regarding inheritance. The Redfish openapi.yaml uses AnyOf in multiple places (see swagger.io/docs/specification/data-models/oneof-anyof-allof-not/), such as Redundancy_Redundancy:
anyOf:
- $ref: http://redfish.dmtf.org/schemas/v1/odata-v4.yaml#/components/schemas/odata-v4_idRef
- $ref: http://redfish.dmtf.org/schemas/v1/Redundancy.v1_0_10.yaml#/components/schemas/Redundancy_v1_0_10_Redundancy
- $ref: http://redfish.dmtf.org/schemas/v1/Redundancy.v1_1_8.yaml#/components/schemas/Redundancy_v1_1_8_Redundancy
- $ref: http://redfish.dmtf.org/schemas/v1/Redundancy.v1_2_6.yaml#/components/schemas/Redundancy_v1_2_6_Redundancy
- $ref: http://redfish.dmtf.org/schemas/v1/Redundancy.v1_3_6.yaml#/components/schemas/Redundancy_v1_3_6_Redundancy
- $ref: http://redfish.dmtf.org/schemas/v1/Redundancy.v1_4_1.yaml#/components/schemas/Redundancy_v1_4_1_Redundancy
This increases difficulty for the client to interpret the returned json blob. Specifically, in the generated Java Client code, (see below) it is asking the service to return a special Json field {"type": "OdataV4IdRef"}
@jsontypeinfo(
use = JsonTypeInfo.Id.NAME,
include = JsonTypeInfo.As.PROPERTY,
property = "type")
@jsonsubtypes({
@jsonsubtypes.Type(value = OdataV4IdRef.class, name = "OdataV4IdRef"),
@jsonsubtypes.Type(value = RedundancyV1010Redundancy.class, name = "RedundancyV1010Redundancy"),
@jsonsubtypes.Type(value = RedundancyV118Redundancy.class, name = "RedundancyV118Redundancy"),
@jsonsubtypes.Type(value = RedundancyV126Redundancy.class, name = "RedundancyV126Redundancy"),
@jsonsubtypes.Type(value = RedundancyV136Redundancy.class, name = "RedundancyV136Redundancy"),
@jsonsubtypes.Type(value = RedundancyV141Redundancy.class, name = "RedundancyV141Redundancy")
})
public interface RedundancyRedundancy {
}
I don't expect any Redfish implementation to return the extra Json field for indicating the type. Is there any way to disable the inheritance? Do you see any issue if I trim the openapi file to always use the latest version schema? |
|
|
|
Post by mraineri on Jul 20, 2023 1:36:00 GMT
Yes, those anyOf statements certainly cause complexities; it's an unfortunate modeling pattern we fell into with JSON Schema. We've been hesitant on pruning the anyOf list since our intent is to be a superset of all possible implementations, so if you're a client interacting with multiple systems from different vendors, this gives you hints as to what the payload will look like depending on the version supported by a given implementation.
However, you're certainly free to prune that list for yourself. But since our intent is also to maintain compatibility with previous versions of the schema, maybe it's time we consider only pointing to the highest version of the schema. I can raise this with others to discuss more.
|
|
|
|
Post by jokyjang on Jul 24, 2023 16:50:29 GMT
If the Redfish standard keeps the API backward compatibility, there is no reason to model this with AnyOf since the latest version will always be a super set of older versions. I will prune the models for now for our own interest. Just want to make sure that there is no any legal or licensing issues modifying the models?
|
|
|
|
Post by mraineri on Jul 24, 2023 17:42:06 GMT
Yes, when we make new minor versions of schema they are backwards compatible (at least that's our intent).
There shouldn't be any licensing issues. We do permit schema modifications, and this would fall in something we allow per the spec. The only legal aspect is to preserve the copyright statement to maintain attribution to DMTF; I'm also not a lawyer, but this is our intent.
|
|
