Fork me on GitHub
#clojure-uk
<
2021-01-29
>
dharrigan06:01:36

Buongiorno!

3
cdpjenkins08:01:38

Bună dimineaţa!

dharrigan08:01:14

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

dharrigan08:01:18

Give me strength!

dharrigan08:01:35

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

dharrigan08:01:24

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

djm08:01:12

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

djm08:01:22

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

dharrigan08:01:58

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

dharrigan08:01:51

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

dharrigan08:01:12

rant rant rant

cdpjenkins10:01:27

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.

💯 3
mccraigmccraig11:01:48

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

alexlynham10:01:38

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

Rachel Westmacott10:01:29

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

alexlynham10:01:00

not sure about other langs

alexlynham10:01:09

does rely on consistency though >_>

Rachel Westmacott10:01:25

ah, so no use in the real world then!

Aleksander10:01:48

I up you with Proto/Flat Buffers

dharrigan10:01:32

Don't talk to me about Protobuffers

Conor10:01:09

It's like a normal buffer but more protozoan

dharrigan10:01:07

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

dharrigan10:01:21

Vital systems, so has to be done carefully

danielneal10:01:11

Does anyone have an opinion on malli vs spec?

danielneal10:01:30

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

danielneal10:01:37

so I think we should settle on one

dharrigan10:01:55

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

Rachel Westmacott10:01:58

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

Aleksander11:01:10

unless everyone on the project retires before it happens

dharrigan10:01:19

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

alexlynham10:01:44

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

dharrigan10:01:56

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

dharrigan10:01:25

I think the github page lists it's benefits: ,

dharrigan10:01:43

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

Rachel Westmacott10:01:04

is swagger useful?

dharrigan10:01:20

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

dharrigan10:01:27

I'm so-so about it.

Rachel Westmacott10:01:39

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

dharrigan10:01:52

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

👍 3
danielneal10:01:44

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

Rachel Westmacott10:01:46

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.

danielneal10:01:58

so we need something to document our api

👍 3
danielneal10:01:15

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

dharrigan10:01:22

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

dharrigan10:01:35

by running tests against your exposed APIs, it autogenerates documentation

danielneal10:01:43

wow that's clever

dharrigan10:01:02

Here's an example

dharrigan10:01:20

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

dharrigan10:01:41

those snippets of code are real actual test results

danielneal10:01:15

how is the rest of the document constructed?

danielneal10:01:33

it looks really good

dharrigan10:01:36

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

dharrigan10:01:48

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

danielneal10:01:23

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

dharrigan10:01:26

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

====== Request Headers

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

====== Example HTTPie Request

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

mamapitufo10:01:32

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

dharrigan10:01:49

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

rickmoynihan16:01:20

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

rickmoynihan16:01:42

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

danielneal16:01:56

haha, something like that

dharrigan10:01:52

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

alexlynham10:01:40

swagger is good

alexlynham10:01:47

i see it as docs for free

danielneal10:01:08

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

alexlynham10:01:15

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'

alexlynham10:01:25

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

dharrigan10:01:55

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

dharrigan10:01:16

the <1> etc...

danielneal10:01:36

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

dharrigan10:01:42

does all that

dharrigan11:01:24

and this for admonitions

dharrigan11:01:27

I do like me Asciidoc

dharrigan11:01:05

This one is a bit prettier

danielneal11:01:59

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?

danielneal11:01:49

I really really like the idea of combining tests and documentation

3
danielneal11:01:48

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

danielneal11:01:14

but that's for clojure tests

danielneal11:01:26

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

mccraigmccraig11:01:08

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

dharrigan11:01:34

You can generate json schema from malli, aka

dharrigan11:01:48

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

danielneal12:01:34

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

Conor12:01:42

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

😄 3
danielneal12:01:43

haha maybe I don't mean superset and subset

danielneal12:01:08

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

Conor12:01:12

I guess they intersect to some degree!