You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We've got an API schema set up using JSON API, and we've got some required fields which are shared between several different API methods. As such, we'd like to include a $ref that defines the API attributes in one place. I dug a bit into the schemata templates which generate the documentation, and while it does attempt to recurse down some things, it seems that when it's deciding which attributes are required, it doesn't do so in a way which allows it to expand $refs.
I tried to strip down our schema a bit to illustrate the issue:
I think attributes may nest those properties more deeply than I would expect? Outside that, one option might be to leave the attributes as they are, but just move the requires directly to the shared definition and pull it out to be along-side the other properties. My suspicion is definitely a mismatch with expected nesting levels of some sort, fwiw.
We've got an API schema set up using JSON API, and we've got some required fields which are shared between several different API methods. As such, we'd like to include a $ref that defines the API attributes in one place. I dug a bit into the schemata templates which generate the documentation, and while it does attempt to recurse down some things, it seems that when it's deciding which attributes are required, it doesn't do so in a way which allows it to expand $refs.
I tried to strip down our schema a bit to illustrate the issue:
https://github.com/lukeschlather/nested-jsonapi-example/blob/master/docs/schemata/person.yaml
You can see for example that both the "create" and "batch create" operations are supposed to share the /schemata/person#/definitions/resource-without-revision properties, which define the "required" fields for a person. You can see here the generated markdown: https://github.com/lukeschlather/nested-jsonapi-example/blob/master/source/index.html.md
Note that all of the "Create" fields are listed as optional, rather than required.
I was curious if you could implement this in prmd, or if you have any suggestions about how to implement it I could also take a look.
The text was updated successfully, but these errors were encountered: