https://kotlinlang.org logo
Channels
100daysofcode
100daysofkotlin
100daysofkotlin-2021
advent-of-code
aem
ai
alexa
algeria
algolialibraries
amsterdam
android
android-architecture
android-databinding
android-studio
androidgithubprojects
androidthings
androidx
androidx-xprocessing
anime
anko
announcements
apollo-kotlin
appintro
arabic
argentina
arkenv
arksemdevteam
armenia
arrow
arrow-contributors
arrow-meta
ass
atlanta
atm17
atrium
austin
australia
austria
awesome-kotlin
ballast
bangladesh
barcelona
bayarea
bazel
beepiz-libraries
belgium
benchmarks
berlin
big-data
books
boston
brazil
brikk
budapest
build
build-tools
bulgaria
bydgoszcz
cambodia
canada
carrat
carrat-dev
carrat-feed
chicago
chile
china
chucker
cincinnati-user-group
cli
clikt
cloudfoundry
cn
cobalt
code-coverage
codeforces
codemash-precompiler
codereview
codingame
codingconventions
coimbatore
collaborations
colombia
colorado
communities
competitive-programming
competitivecoding
compiler
compose
compose-android
compose-desktop
compose-hiring
compose-ios
compose-mp
compose-ui-showcase
compose-wear
compose-web
confetti
connect-audit-events
corda
cork
coroutines
couchbase
coursera
croatia
cryptography
cscenter-course-2016
cucumber-bdd
cyprus
czech
dagger
data2viz
databinding
datascience
dckotlin
debugging
decompose
decouple
denmark
deprecated
detekt
detekt-hint
dev-core
dfw
docs-revamped
dokka
domain-driven-design
doodle
dsl
dublin
dutch
eap
eclipse
ecuador
edinburgh
education
effective-kotlin
effectivekotlin
emacs
embedded-kotlin
estatik
event21-community-content
events
exposed
failgood
fb-internal-demo
feed
firebase
flow
fluid-libraries
forkhandles
forum
fosdem
fp-in-kotlin
framework-elide
freenode
french
fritz2
fuchsia
functional
funktionale
gamedev
ge-kotlin
general-advice
georgia
geospatial
german-lang
getting-started
github-workflows-kt
glance
godot-kotlin
google-io
gradle
graphic
graphkool
graphql
graphql-kotlin
graviton-browser
greece
grpc
gsoc
gui
hackathons
hacktoberfest
hamburg
hamkrest
helios
helsinki
hexagon
hibernate
hikari-cp
hire-me
hiring
hongkong
hoplite
http4k
hungary
hyderabad
image-processing
india
indonesia
inkremental
intellij
intellij-plugins
intellij-tricks
internships
introduce-yourself
io
ios
iran
israel
istanbulcoders
italian
jackson-kotlin
jadx
japanese
jasync-sql
java-to-kotlin-refactoring
javadevelopers
javafx
javalin
javascript
jdbi
jhipster-kotlin
jobsworldwide
jpa
jshdq
juul-libraries
jvm-ir-backend-feedback
jxadapter
k2-early-adopters
kaal
kafka
kakao
kalasim
kapt
karachi
karg
karlsruhe
kash_shell
kaskade
kbuild
kdbc
kgen-doc-tools
kgraphql
kinta
klaxon
klock
kloudformation
kmdc
kmm-espaƱol
kmongo
knbt
knote
koalaql
koans
kobalt
kobweb
kodein
kodex
kohesive
koin
koin-dev
komapper
kondor-json
kong
kontent
kontributors
korau
korean
korge
korim
korio
korlibs
korte
kotest
kotest-contributors
kotless
kotlick
kotlin-asia
kotlin-beam
kotlin-by-example
kotlin-csv
kotlin-data-storage
kotlin-foundation
kotlin-fuel
kotlin-in-action
kotlin-inject
kotlin-latam
kotlin-logging
kotlin-multiplatform-contest
kotlin-mumbai
kotlin-native
kotlin-pakistan
kotlin-plugin
kotlin-pune
kotlin-roadmap
kotlin-samples
kotlin-sap
kotlin-serbia
kotlin-spark
kotlin-szeged
kotlin-website
kotlinacademy
kotlinbot
kotlinconf
kotlindl
kotlinforbeginners
kotlingforbeginners
kotlinlondon
kotlinmad
kotlinprogrammers
kotlinsu
kotlintest
kotlintest-devs
kotlintlv
kotlinultimatechallenge
kotlinx-datetime
kotlinx-files
kotlinx-html
kotrix
kotson
kovenant
kprompt
kraph
krawler
kroto-plus
ksp
ktcc
ktfmt
ktlint
ktor
ktp
kubed
kug-leads
kug-torino
kvision
kweb
lambdaworld_cadiz
lanark
language-evolution
language-proposals
latvia
leakcanary
leedskotlinusergroup
lets-have-fun
libgdx
libkgd
library-development
lincheck
linkeddata
lithuania
london
losangeles
lottie
love
lychee
macedonia
machinelearningbawas
madrid
malaysia
mathematics
meetkotlin
memes
meta
metro-detroit
mexico
miami
micronaut
minnesota
minutest
mirror
mockk
moko
moldova
monsterpuzzle
montreal
moonbean
morocco
motionlayout
mpapt
mu
multiplatform
mumbai
munich
mvikotlin
mvrx
myndocs-oauth2-server
naming
navigation-architecture-component
nepal
new-mexico
new-zealand
newname
nigeria
nodejs
norway
npm-publish
nyc
oceania
ohio-kotlin-users
oldenburg
oolong
opensource
orbit-mvi
osgi
otpisani
package-search
pakistan
panamĆ”
pattern-matching
pbandk
pdx
peru
philippines
phoenix
pinoy
pocketgitclient
polish
popkorn
portugal
practical-functional-programming
proguard
prozis-android-backup
pyhsikal
python
python-contributors
quasar
random
re
react
reaktive
realm
realworldkotlin
reductor
reduks
redux
redux-kotlin
refactoring-to-kotlin
reflect
refreshversions
reports
result
rethink
revolver
rhein-main
rocksdb
romania
room
rpi-pico
rsocket
russian
russian_feed
russian-kotlinasfirst
rx
rxjava
san-diego
science
scotland
scrcast
scrimage
script
scripting
seattle
serialization
server
sg-user-group
singapore
skia-wasm-interop-temp
skrape-it
slovak
snake
sofl-user-group
southafrica
spacemacs
spain
spanish
speaking
spek
spin
splitties
spotify-mobius
spring
spring-security
squarelibraries
stackoverflow
stacks
stayhungrystayfoolish
stdlib
stlouis
strife-discord-lib
strikt
students
stuttgart
sudan
swagger-gradle-codegen
swarm
sweden
swing
swiss-user-group
switzerland
talking-kotlin
tallinn
tampa
teamcity
tegal
tempe
tensorflow
terminal
test
testing
testtestest
texas
tgbotapi
thailand
tornadofx
touchlab-tools
training
tricity-kotlin-user-group
trójmiasto
truth
tunisia
turkey
turkiye
twitter-feed
uae
udacityindia
uk
ukrainian
uniflow
unkonf
uruguay
utah
uuid
vancouver
vankotlin
vertx
videos
vienna
vietnam
vim
vkug
vuejs
web-mpp
webassembly
webrtc
wimix_sentry
wwdc
zircon
Powered by
Title
d

dave

09/12/2019, 1:09 PM
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/
d

DALDEI

09/13/2019, 4:01 AM
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
d

dave

09/13/2019, 8:04 AM
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. šŸ™‚
d

DALDEI

09/16/2019, 6:35 AM
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.kjetland:mbknor-jackson-jsonschema_2.12:1.0.34' , 'com.dr:ktjsonschema:1.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.
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 !