https://kotlinlang.org logo
Join SlackCommunities
Powered by
What's the best way to generate a site of document...
# ktor
s
What's the best way to generate a site of documentation for a ktor API? The ktor plugin is pretty bad. I've tried some of the open source plugins for generating an open api spec and have been surprisingly disappointed.
a
s
Kompendium was what we tried
a
Afaik, kompendium is the best openapi generator available for Ktor. If you need better, you may have look into a web toolkit with better support, like Javalin or Http4k.
r
out of curiosity... what did you have trouble w/ when using kompendium? I am the creator 🙂 happy to answer any Qs if you have them
c
@Ryan Brink I think the biggest issue is that you only export OpenAPI 3.1.0 definition and Swagger UI only support 3.0.X
s
We're considering using https://github.com/SMILEY4/ktor-swagger-ui This seems like what we'd expect from the API.
r
Yea this was intentional, 3.1 spec is much nicer because it is fully json schema compliant. But good news, as of a couple months ago swagger supports 3.1 This PR showcases someone using it in kompendium https://github.com/bkbnio/kompendium/pull/426
c
sure I can “fake” the openapi version to say its 
3.0.0
but its not officialy supported https://github.com/swagger-api/swagger-ui#compatibility
r
Did u look at the pr? It’s natively supported
c
ah, the PR is goining the other route, using a alpha version of swagger ui.
r
Yes, V5
c
until this is released https://editor.swagger.io/ will not work with the definition you create. anyway, just my 2 cents why someone might not use your library.
r
Sure :) tho, to be fair, the very first thing in our docs is a version matrix showing you what openapi spec we generate. So… not much more we can do there
👍 2
fwiw i just opened that editor out of curiosity (pretty neat never used it before), and they have a link right at the top to their "next" editor that does support 3.1 https://editor-next.swagger.io
including async-api, which is a feature i've wanted to add to kompendium but just haven't found the time 👀
c
is there a way to omit the empty verbs? I have this as the defintion:
Copy code
private fun Route.documentation() {
    install(NotarizedRoute()) {
        tags = setOf("Profile")
        get = GetInfo.builder {
            summary("Profile")
            description("Fetch the profile information")
            response {
                responseCode(HttpStatusCode.OK)
                responseType<Profile>()
                description("The profile object")
            }
        }
    }
}
Untitled.json
more feedback: the “builder” dsl is a little verboce in not telling which parameters are manadatory.
all mendatory parameters should be part of the “constructor”.
r
is there a way to omit the empty verbs?
this is up to your serializer, not kompendium. for example if you are using kotlinx serialization, you would want to configure the content negotiation to use a Json encoder that does not use explicit nulls
Copy code
Json {
          encodeDefaults = true
          explicitNulls = false
          serializersModule = KompendiumSerializersModule.module
        }
more feedback: the “builder” dsl is a little verboce in not telling which parameters are manadatory.
yes, I feel the same way. I believe there was a reason I chose this option over the constructor approach, but I can't recall off the top of my head
kompendium uses the serializer you have attach to your app
c
no I don’t mean the type serialization, I mean the empty http verbs 
put
, 
post
..
r
you are encoding nulls, so you currently have 
put: null
... as to why that shows in the editor as a valid route, i do not know
but the openapi spec is correct as far as I can tell
c
you would want to configure the content negotiation to use a Json encoder that does not use explicit nulls
No, I dont want to change my serializer for the whole backend. is there a way to set the serializer in the 
NotarizedXXX
???
r
no, this isn't how serialization works for Kompendium. The entire spec is calculated at server startup, and served from a single endpoint. Hypothetically, you could serve individual json schemas for each route, but that would be a huge undertaking
this is a bug w/ the UI, not w/ kompendium
c
but the openapi spec is correct as far as I can telL
the json validator complains as well
r
afaik it is valid to return null for this, if you can find documentation stating otherwise, feel free to open an issue on github
c
It’s fine, with all those little “issues” your library is not usable for me. Good luck with it and 🤞
r
nobody was asking you to 🙂
👍 1
c
no but you where asking
out of curiosity... what did you have trouble w/ when using kompendium? I am the creator 🙂 happy to answer any Qs if you have them
if you write a library you should be open to feedback and how other use it. 😉
r
Did I not answer your questions?
c
Answer, sure.
what you do with my feedback is up to you.
r
Maybe you are new to open source (if so welcome 👋) usually the best way to help is to file any bugs (with evidence) as a ticket on github.
c
I will, and thanks, I know how it works 😉
9 Views
Open in Slack
PreviousNext
Powered by