search

SMILEY4 / ktor-swagger-ui

Kotlin Ktor plugin to generate OpenAPI and provide Swagger UI
Apache License 2.0
150 stars 25 forks source link

Too complex #74

Closed s949492225 closed 8 months ago

s949492225 commented 9 months ago

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.

SMILEY4 commented 9 months ago

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 ?

s949492225 commented 9 months ago

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 image java image python image nodejs image

SMILEY4 commented 9 months ago

thanks, some of my thoughts about this

  1. 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.

  2. 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.

  3. 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.

s949492225 commented 9 months ago

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.

SMILEY4 commented 8 months ago

Yes, in my opinion, that is why there is less"code" compared to the ktor-plugin

s949492225 commented 8 months ago

Yes, it would be nice if it could completely separate api, param, and response documentation