Swagger

[johannesschobel]

Dear @danivek ,

thank you very much for this demo project showcasing the use of your json-api-serializer and express.js. I stumbled upon a question, you may be able to answer:

You are manually generating the swagger.json file in the docs folder, right? This means, you are currently manually defining the input and output structures of the JsonAPI objects that are sent / returned by the API, right?

Would it be possible to auto-generate these information? E.g., the structure of the paginated /articles route? Because currently, i see the following issue:

1. You must define your own "internal model" of the Article (e.g,. the structure of the model how it is stored in the database).
2. Then you are defining the serializer where you are (partially) re-writing information (e.g., how are fields mapped, which fields are the attributes to be serialized, and so on)
3. Then, again, you would need to create some kind of "output model" (plain class that you actually NEVER use in your application) to tell Swagger how the data actually look like

I mean, 1 & 2 are steps you actually need to do - there is not much to talk about this.. But 3 seems kind of redundant.. Do you get what i mean?!

I am totally aware that Json:API and Swagger - kind of - are orthogonal with their goals.. e.g., Json:API aims at providing a clear structure how the documents must look like, how routes are formed, which query params are valid and so on.. Swagger, on the other, aims at providing some kind of explorative documentation - that allows for automatically generating code snippets to interact with the API.

So the next question could be: Is it possible to use the best of both approaches? Like, get the "structure" of the data that is serialized by the Serializer and then - somehow - use this information within Swagger? Do you have any ideas / suggestions on this?

All the best