
Taming OpenAPI using Racket to create a DSL - spdegabrielle
https://developer.squareup.com/blog/making-openapi-swagger-bearable-with-your-own-dsl/
======
seandhi
I don’t see that quote in the article at all, and it doesn’t appear that the
author claims any kind of trickery or sneakiness to trick his team into using
Racket. It seems like the team built the tool together.

~~~
neilv
Yes, I don't see any mention of trickery in the article. For the record,
capital-R Racketeers do not condone trickery.

~~~
ken
That's a surprise! It sounds like the first in its line. As Wikipedia says:

> Scheme was originally called "Schemer", in the tradition of other Lisp-
> derived languages such as Planner or Conniver.

If there's any programming language family which condones trickery, I would
think this would be it.

~~~
neilv
Whatever the goals of all the Scheming, it doesn't seem to have involved
monetary wealth. :)

------
yowlingcat
The idea of using a DSL to get around constraints in an upstream language you
don't control is indeed a nice one, and one I've used before to a good degree.

I'm sure I'm going to get downvoted for this, but the use of Racket is a smell
here. Why not use whatever language you were using before to turn the input
DSL into the output OpenAPI spec? Sooner or later, another engineer is going
to have to maintain that. You already have another language you're using for
other things, and you're introducing an entirely new language and ecosystem to
do one small thing. Is this something that couldn't be done in your existing
stack?

------
BerislavLopac
> Problem: while OpenAPI is great for describing APIs, generating client SDK
> code and defining your API contracts, it's definitely not a great experience
> to write OpenAPI documents from scratch.

Personally, my main problem with OpenAPI is that it is commonly used for
documenting contracts, but very rarely for actually driving the
implementation. In practice, I have seen a few implementations like OpenAPI
Generator [0] but a) with dynamic languages like Python code generation is an
anti-pattern, and b) even disregarding the former, the generated result is (in
my experience) very incomplete and still needs a lot of manual coding.

I would like to see more frameworks that utilise OpenAPI for routing and
request/response validation.

[0] [https://openapi-generator.tech/](https://openapi-generator.tech/)

~~~
jbreiding
Sorry, I've heard this statement a few times, code generation in dynamic
languages is an anti pattern. Do you happen to have any more reading on this?

Sure the generated code is usually not readable which is against the zen of
python. But writing code to generate code, especially if it's contract driven,
is the correct approach no matter the language.

So really what I'm looking for is more substance of why generating code is an
anti pattern in python but not in C.

~~~
ptx
My personal feeling is that it just doesn't fit into the workflow. With C you
always have a compilation step and thus a build process, so a code generation
step fits quite naturally into your makefile (or other build script).

With Python there's normally no build step – you just run the program. Adding
code generation means adding another step, which you might forget to run,
leading to confusion. If you make the build step mandatory you lose some of
the upside of dynamic languages.

~~~
jbreiding
I've always solved this with unit/functional tests. The test runner
effectively acts as a compiler, for the purposes of checking the contact. in
this process.

This is something that's baked into a gate check on merge to the source repo.
Or rather it should be.

------
sametmax
Why didnt they use the language they already coded the API in then ?

~~~
king_magic
This is where I’m really struggling with this story. Now, they have two places
documentation can reside: in the code for the API itself, and now in a
separate file encoded with a custom LISP-like language?

I feel like the author is forgetting how software gets developed in the real
world... or just human nature in general.

Documentation created with this approach will instantly go stale, and will
likely get out of sync with the true API very quickly.

How is this a good solution at all? How is “tricking” people into this
unsustainable situation a good thing?

~~~
amelius
I'm guessing the real plan is to trick the co-workers into rewriting the
entire application in Racket.

~~~
yowlingcat
It really irks me how some treat the practicalities and existing choices of
real world software development as an annoying impediment to getting to use a
language they're interested in. Whether you're interested in a language and
whether you should use it in production can be two separate things. If you've
got a compelling reason to use a given language in production, you probably
don't have to trick your co-workers into doing anything, you just have a
conversation with them! And if you "trick" them into using it for something
small, aren't you going to sabotage your long term relationship and trust with
them for minimal gain?

~~~
detaro
> _If you 've got a compelling reason to use a given language in production,
> you probably don't have to trick your co-workers into doing anything, you
> just have a conversation with them!_

Nothing in the article suggests that conversation didn't happen. The only
mention of "tricked" is the headline the submitter gave it on HN.

------
nudpiedo
Little good nice story of how to introduce a new tool for work without getting
into a crusade. I guess however the manager/architect didn't care much of the
additional dependency added to the project thought.

------
sulami
I’ve recently built a thing at work to generate an OpenAPI spec from Clojure
specs and some annotations, which worked out surprisingly well. We already
have a collection of endpoints through compojure, and we just spec the handler
functions and add some annotations for docstrings, and that’s basically it. As
an added bonus we have the test suite validate all api calls against the spec,
so in theory the OpenAPI spec should always be accurate.

For the curious, we took and hacked [https://github.com/metosin/spec-
tools](https://github.com/metosin/spec-tools) to output OpenAPI 3, and added a
very thin shim to hook that up to our routes.

------
tjalfi
It isn’t clear whether they already use Racket.

If Racket was added for this purpose then here are a couple boring[0]
solutions that could have lower operational costs.

Generate OpenAPI specifications from your service code.

Use a YAML preprocessor/template engine such as [1]. I have used a similar
technique to generate SQL queries.

[0] [https://mcfunley.com/choose-boring-
technology](https://mcfunley.com/choose-boring-technology)

[1] [https://github.com/con2/emrichen](https://github.com/con2/emrichen)

------
WhitneyLand
Seems like it could be convenient to use typescript in some way. Not to code
the DSL, but as the DSL itself.

It's language specific, but if a variation with minor attributing extensions
existed that seamlessly round-tripped to yaml, the verbosity would just
completely collapse.

Readability and creating from scratch could be an order of magnitude more
efficient for anyone familiar with JS (reading a handful of interface
definitions vs. human parsing back and forth between the docs and YAML).

------
JoelMcCracken
Generally, this technique can work for adding any kind of pet tech to your
work stack:

\- identify an isolated, low-risk need.

\- develop a solution in your tech (usually on your own time).

\- introduce to your boss/company as already developed.

The biggest risk for the business is needing to replace the component. In
these cases usually an isolated, irregular solution is acceptable

~~~
yowlingcat
Why the phrase "pet tech"? This is a good way to "ask for forgiveness, not
permission" which I approve of. But is the goal of adding "pet tech"
necessarily a good one? If technology is actually going to move your firm
forward long term and is a good long term decision, it's not pet technology.
It's a good decision, and it's something that hopefully your team and firm is
behind.

~~~
marcinzm
If it's a good decision then you shouldn't have to ask for forgiveness rather
than permission. It's also, if it's not just a pet technology, a strategic
decision that impacts everyone on your team and it's pure ego to think you
should make that decision alone.

~~~
yowlingcat
I agree with both points. I do think there are orgs where, due to shall we say
"personality constraints" you can have majority consensus that a decision is
good and should be made but it can still get roadblocked. Of course, such
situations are an indicator of a dysfunctional org; in a functional one, you
have these kinds of open discussions and like you said, you don't need to ask
for forgiveness rather than permission, and you can make these strategic
decisions together as a team.

------
Smithalicious
Please don't try to nest quotes of the same kind like this. It reads as 3
parts, quoted - unquoted - quoted, and makes no sense like that.

Yes this is a very pedantic thing to complain about and I do understand what
is meant. But it does bother me. Yes, I do realize it's using slanted quotes
and not just " \- still doesn't read right for me.

------
marcinzm
edit: Got confused by the title not actually matching the article title and
having click-bait information added to it that didn't appear in the original.

~~~
detaro
Which part of the article(!) suggests to you they didn't have that discussion?

~~~
marcinzm
The word tricked.

~~~
detaro
Where in the article does it appear? From what I see, the only claim in that
direction is the random(?) headline the submitter added here. And even then,
it doesn't have to be interpreted that way - it could also apply to "they'd
normally not consider a language like this, but for this specific case it
seemed to make sense".

~~~
marcinzm
Good point, didn't realize they changed the original title since that's almost
almost frowned upon on HN.

------
sergiotapia
Now you are the single point of failure for this service, and worse, you
forced your team to learn something they may have had zero interest in looking
into.

Never do this in prod without a heads up and approval from most of your team.

I worked with a guy who after completing his tickets instead of looking for
more tickets or helping his team, spent his time rewriting the entire
clientside application in typescript. He was let go the following month.

~~~
detaro
Am I missing something? The only thing pointing in that direction I see is the
submission title here on HN, which is in no way reflected in the article?

~~~
sergiotapia
No mention in the article but the title is clearly implying that.

~~~
detaro
Which is the title on HN, not the title of the article.

