We've added a tutorial about the http4k OpenApi3 s...

# server

[dave]

We've added a tutorial about the http4k OpenApi3 support to the website. Feedback (or upvotes 🙂 ) very welcome: https://www.reddit.com/r/Kotlin/comments/d36z03/tutorial_documenting_http4k_apis_with_openapi3/

[DALDEI]

FINALLY ... (not you -- ANYONE)
Body Declarations.

unscientficially I estimate of the 'swagger'. or 'openapi' specs for APIs Ive seen and used maybe 1 of 10 even attempt a body (for more then application/json )
Those that do, maybe 50:50 is it acurate or docuemted.

This is exciting -
And
has a ways to go ...
Please take with with "11" as your 1-10 score -- but Im tring for 20 🙂

If I read this right the actual code and data returned from the API is not whats used for the spec.
ex: spec generated from returning( ...)
Where the actual API is implemented via ::handler

besides "its really hard" 🙂 -- why this separation ? Why not take the return type of handler (or some other signature component ) directly ?
http4k has I bevlie basic json schema gen code built in, and there are several decent ones that generate decent JSON schema from class objects.
I have used these successfully -- to genreate JSON schema .. but have wanted to but not gotten around to -- plopping that into the whole enchilada.
Why stop short of no-duplication-of-truth ?
I'll give up examples in favor or accurate define-once-and-only-once body schema , preferably if in fact its the same (literal/code source) instance as the implemenation. Your SO CLOSE

[dave]

The approach was due to a combination of things. I'm sure there are others, but off the top of my head:
1. it's really hard.
2. I kind of agree about the duplication, but I think this is a reasonable balance with regards to the simplicity of API - because we're concentrating on just providing a simple shim over the top of the HttpHandler interface, I'm not sure how we would structure the API to capture that "type" without interfering with the ability to custom construct the HTTP response. IMHO I think this is the mistake that other libraries make - they hide the realities of the HTTP protocol from the user by "just returning an object" from some method.
3. we didn't come across any decent class to JsonSchema converters out in the wild that supported the version of JsonSchema that OpenApi uses (happy to be wrong on this! 🙂 ). Reflection over class structures is even more knarly than doing it over instances (from my experience).
4. OpenAPI is actually "example driven" anyway and these do appear as supplied in the API docs - by using an actual class instance we can supply values of fields (eg. strings) which guide the user to supply correct values as opposed to "it's a string". Since http4k doesn't support the (admittedly limited) per-field validations that are present in the OpenApi spec, this is possibly more important. If we did it based on reflection we wouldn't know how to populate these example values.
5. there is special difficulty around fields which are multi-value (eg. an array containing different implementations of a particular interface). Obviously for singular this is a problem with the instance-based version as well, but (somewhat) amusingly the OpenApi UI doesn't actually currently support multi-response/request modelling - you can specifiy it in the OpenApi spec but the UI breaks during rendering.
6. it's consistent - if you don't choose to use Jackson (which is the only JSON implementation which will accurately generate the JSON schema fully), you still have the opportunity to supply a JSON node and you'll get the 'object-XYZ' based schema breakdown. This obviously doesn't actually have any real schema separation for field objects because JSON is untyped (and for the autoschema gen we do it based on JVM class).
7. it's (still) really hard. 🙂

[DALDEI]

1,7 yes its hard - but thats what library authors are born for -- to do the hard stuff for us mortals to abuse 🙂
2. "return Object" -- yes pointelss. Im refering more to return "class X" or "interface X", (and accept class X)
3. The schema modules Ive been using are 'com.kjetlandmbknor jackson jsonschema 2.121.0.34' , 'com.drktjsonschema1.0.2' YMMV.
--> I have a gradle plugin that given an annotated class or interface will generate json schema from it and leave it as 'source' in your build tree
I do not know if this is compatible with openAPI version-wise or otherwise, but it works reasonably well -- not perfedt but decent (on kotlin code )

4. I would disagree -- There are certianly a section for examples -- which is awesome --- but I disagree its 'example driven' -- e.g. in codegen or as a consumer of openapi, the example's role is only that of plain text, it does not take part in any of the type, structure, or formal specs, not validated against them, nor used in any way except in specialized documentation generators. -- not to say they are not useful, but I disagree that its 'driven' by example. Maybe some implementation may choose to do so similar to how examplatron uses 'examples' to derive XML schema -- but its not in OpenAPI in any form I am aware.
5. Yes some form of allowed openapi schema are not easly represented in kotlin or java -- but if your codebase is kotlin or java maybe you dont use those much ?
6. Constant -- with some aspects, inconsistent with others - not saying its bad -- just that consistency is context dependent.
7. Ya , hard. thats why I dont do it (yet)) -- but you !!! -- you da man - you can do this before breakfast 🙂 -- does encouragement help?
IMHO most difficult is integration cleanly with http4k existing 'isms' but the lense thing comes close -- say if you restricted any one method to a single lens of class/interface --then you got it.

[DALDEI]

OTOH -- all said Above -- doesn't mean that *it should be done that way * -- Im still searching for the Holy Grail where one can use ONE and ONLY ONE type declaration that defines contract for function, APIs' (of various sorts), serialization, documentation, validation, configuration, and cleans behind my ears after dinner. Still frustrated with the inabilty of Kotlin to define a class based on an interface without having to literally duplicate every thing -- for the simple case why cant I do 'data class X : I --> if I is a pure property based interface ..
Thats just Not RIght !