I started using OpenAPI a few months ago, but I'm finding multiple caveats while generating documentation. This of course leads me to believe that I must be doing something wrong.
So, I usually begin always by creating the schemes for the multiple resources of my API, I then place a reference to the schemes on the request bodies for each respective endpoint. However I find that this approach makes generated documentation confusing, adding for example an id parameter on the request body of a user create operation when it's clearly not supposed to be there (Of course the user is being created at this point, so there isn't even an ID in the first place, and why would an ID be part of the request body?).
I ended up just making multiple schemes for a single data model, I would choose which one I used based on the operation (E.g. Creating vs Displaying), this way I could generate documentation more accurately. This helps me avoid situations like displaying relations that are generated post-creation on a create operation. (I know I'm probably not phrasing all this correctly but just bear with me).
In a nutshell, I'll end up with approximately 3 or 4 schemes per data model. For the User model I'll have for example User, UserNew, UserSubscriptions, UserAll. All schemes represent the same resource, they just differ in the data that they display.
Again, I feel like this is not the way that OpenAPI is meant to be used. So I hoped that maybe someone here that has more experience with this could guide me on the right path! Thank you.
