Too complex
s949492225 opened this issue · comments
ktor itself is very simple, and does not match with such a complex swagger sdk. Can you check the fields and comments together, just like python or java,nodejs, maybe adding full annotations can solve this problem.
Hi, avoiding annotations is an intentional design choice for this plugin and will most likely not be changed. Do you have any specific examples of parts that are too complex or any specific suggestions ?
If you don't need annotations, maybe you can make it simpler
Extreme simplicity and simplicity.
Implement documentation with the minimum number of words.
kotlin
java
python
nodejs
thanks, some of my thoughts about this
-
the swagger library for java can extract more information from the method (e.g. response body, query parameter, ...) than is possible with ktor. I dont know how this is with the other languages (python, js, ...) but this results in less manual documentation compared to ktor. I am trying to detect as much as possible automatically, but there are just technical limitations to this.
-
Annotations in java and kotlin are inheritly limited in what you can do, e.g. only some data types allowed and no complex objects as properties. In my opinion, this makes it really hard to work with them when applied to more complex tasks (i.e. documenting routes beyond basic description and title). In my opinion, the annotation-bases approach becomes almost unreadable for bigger or complex systems.
-
The ktor example provided by you looks bigger, because it adds more details to the route (e.g. multiple resposes, more descriptions, ...) which are not present in the other examples.
I hope this clears some things up. I am always open for suggestions tough.
I'm sorry, my communication is curt. My English is not very good.
The reason why java or python swagger is simple is that the internal documentation of the request and respone itself is inside its mode.
Yes, in my opinion, that is why there is less"code" compared to the ktor-plugin
Yes, it would be nice if it could completely separate api, param, and response documentation