Clojurians Log v2

Buongiorno!

👋

Bună dimineaţa!

moin moin

Yesterday, I spent a lot of my time in Kotlin, fighting with Jackson to ensure that the data I'm reading from an external API fits into the statically defined model...

Give me strength!

I did the same in Clojure, and it was trivially easy to map...

Got it working in the end, but I think I have mild trauma from it

Raise a feature request with JetBrains for ctrl-alt-shift-k to do Clojure -> Kotlin, as well as Java -> Kotlin

I'm sure they'll get right on it 😁

My data model in Kotlin (this isn't a fault of Kotlin per-se!) is littered with`@Json*` annotations...

It doesn't help that the external party's API, obviously done using C# is PascalCase for the field names

rant rant rant

morning

Morn'

morning

PascalCase :face_vomiting: … I feel your pain. Forcing crappy JSON to map onto classes correctly in a statically typed language is the hardest problem in computer scient.

also if you work in a microservice style and a different team has a json api with streetAddress but your team is using street_address lolol

I up you with Proto/Flat Buffers

Man

Don't talk to me about Protobuffers

It's like a normal buffer but more protozoan

We use protobuffers at work and are in the loooong process of ripping them out

Vital systems, so has to be done carefully

Does anyone have an opinion on malli vs spec?

isn't there a library for this, camel_Snake-kebab or something?

I've joined a new codebase and there's spec, plumatic schema and malli

so I think we should settle on one

in clj yes

I use malli a lot. I use reitit to service a RESTful API and malli is soooooooo good.

I imagine the plan is to settle on spec once it's out of alpha...

not sure about other langs

does rely on consistency though >_>

There's a lot of work going on in #malli right now, lots of exciting stuff.

ah, so no use in the real world then!

somebody sell me malli, i've had a lot of success with plumatic/schema in the past

I have used spec as well, but <shrug> malli feels a lot easier to me.

I think the github page lists it's benefits: <https://github.com/metosin/malli>,

for example, with malli and reitit I was able, without hardly any work, to expose a Swagger endpoint.

is swagger useful?

Meh, there's a push for it at work.

I'm so-so about it.

it seems clever but I've never seen the benefit (I can well believe that there is one though)

But, having it done for me is nice, I don't have to spend a lot of cycles working with it,

I'm being pushed to make swagger work too, but it makes more sense for us because we have outsourced the UI and mobile app

At one point I was going to add it because yada apparently made it easy - but there never seemed enough reason to actually do it.

so we need something to document our api

but having tried to read through the 15,000 word openapi3 spec yesterday my brain is mush

I would like to see something borrowed from the Spring world, aka Spring RestDocs

by running tests against your exposed APIs, it autogenerates documentation

wow that's clever

Here's an example <https://toyota.test.txconnected.com/>

that I did, all generated by running unit tests against the exposed API endpoints

those snippets of code are real actual test results

how is the rest of the document constructed?

it looks really good

you have a base template and hooks that the unit tests spit their snippets out into

then asciidoc runs over it and spits out html (or a pdf of whatever)

yeah I was hoping we could somehow kill two birds with one stone with tests and documentation

i.e.,

===== Example 1 (Successful BASIC Authentication)

====== Request Headers

include::{snippets}/authentication-basic/request-headers.adoc[]

====== Example HTTPie Request

include::{snippets}/authentication-basic/httpie-request.adoc[]

something like swagger makes sense when you generate code/validators/types from the spec, as well as documentation. I've used it a couple of times as just the docs part, and it makes no sense to me

Spring RestDocs generates the request-headers.adoc, httpie-request.adoc etc...

I would lurve to see something like that in Clojure Land 🙂

swagger is good

i see it as docs for free

this looks really great, how do these annotations work @dharrigan ? Is that an asciidoc thing?

and right now in a project where we have to field a bunch of questions about what is what and where and why, i'm just like 'ugh, this should be automated'

yes

that said if i had to write swagger by hand, i'd nope out

.JSON Error Response Format
{
    "code": "errorCode", <1>
    "errors": {
      "request": [ <2>
          "Sorry, incorrect data [foo] supplied for [field]. Reason [bar]." <3>
      ]
    }
    "message": "Sorry, there has been a validation problem with the supplied data. Please report the reference code to Support.",
    "reference": "referenceCode" <4>
}
<1> For example `E13000`.
<2> For example `eligibilityCheckRequest`.
<3> For example `Sorry, incorrect data [123456789012345678] supplied for field [vin]. Reason [size must be between 0 and 17]."`
<4> For example `4f35fc4f

the <1> etc...

I see nice. And ascii doc does the structure / index too? (I've not used it before)

Yup

does all that

Very cool

<https://asciidoc.org/userguide.html#X105>

and this <https://asciidoc.org/userguide.html#X28> for admonitions

I do like me Asciidoc

This one is a bit prettier <https://asciidoctor.org/docs/asciidoc-writers-guide/>

So you write the overall template by hand and include references to files that are spit out by the unit tests. So each time you add a new unit test, you add a bit on to your main template, too?

yes

I really really like the idea of combining tests and documentation

:yes:

I used hydrox before, http://helpshift.github.io/hydrox/ but I think zcaudate left the clojure community in storm and fire

unless everyone on the project retires before it happens

but that's for clojure tests

I wonder how much work it would be to do something like spring restdocs

apart from the other problem of cache invalidation and off-by-one errors

malli gives you jsonschema in your swagger doesn't it @dharrigan? or am i having a false memory? lack of jsonschema (for complex content) was always a shortcoming with the swagger autogenerated from yada schema annotations

You can generate json schema from malli, aka <https://github.com/metosin/malli#json-schema>

but I don't see it on the swagger ui when I've fired up my service

openapi3 is both a superset and a subset of json schema (apparently)

If x is a superset and subset of y, doesn't that mean x = y :thinking_face:

haha maybe I don't mean superset and subset

how do you call it when there are properties in openapi3 that are not in json schema, and properties in json schema that are not in openapi3

I guess they intersect to some degree!

I guess you could do that pretty easily with martian and an interceptor: https://github.com/oliyh/martian cc @danieleneal

What’s the advantage of using tests over swagger? Keeping you honest?

haha, something like that