OpenAPI ([docs][openapi-docs], [official spec][openapi-spec])
is a standard format for documenting HTTP APIs. It is
the successor of [Swagger][swagger], also known as OpenAPI 2.

With OpenAPI documentation, you can provide nice interactive docs for
the users of your API ([here's an example using Swagger UI][example]).
They can also automatically generate client code for your API using a
tool like [openapi-generator][openapi-generator] or [the Clojure
library Martian][martian]

[issues]: https://github.com/metosin/reitit/issues
[slack]: https://clojurians.slack.com/archives/C7YF1SBT3
[openapi-spec]: https://learn.openapis.org/specification/
[openapi-docs]: https://spec.openapis.org/oas/v3.1.0
[swagger]: https://swagger.io/
[openapi-generator]: https://openapi-generator.tech/
[martian]: https://github.com/oliyh/martian
[example]: https://petstore3.swagger.io/

## Cool Features in OpenAPI 3

Why should you care about OpenAPI 3 when Swagger works just fine? Some
of the additions that OpenAPI 3 brings might be crucial for
documenting your API properly.

Most significantly, OpenAPI 3 brings full
[JSON Schema](https://json-schema.org/) support. This means that you can
express richer schemas, for example via the operators `oneOf`, `anyOf`
and `allOf`. These operators were present as partially-supported
extensions in Swagger, but in JSON Schema and OpenAPI 3, they have
full support.

Relatedly, you can use _discriminators_ to pick which schema applies
to a value based on a field. This is crucial for big union types like
events. Here's a nice
[blog post on these new features](https://redocly.com/docs/resources/discriminator/).
Note that as of this release, Reitit does not know how to
generate discriminators automatically for you.

OpenAPI 3 also lets you specify different schemas for different
request/response content types. Also, you can specify multiple named
examples for parameters. You can find examples of both of these in the
[Reitit example discussed below](https://github.com/metosin/reitit/tree/master/examples/http-swagger).

On the authentication side, OpenAPI 3 has added support for cookie
parameters & authentication, and better OAuth / OpenID Connect
support. See [the spec](https://spec.openapis.org/oas/v3.1.0#security-scheme-object)
for more info.

## Example

Generating OpenAPI 3 documentation from Reitit is straightforward.
Just use `create-openapi-handler` to define a route. The OpenAPI docs
will be generated based on the route data like `:summary`,
`:parameters`, etc.

```clj
[["/openapi.json"
 {:get {:no-doc true
 :openapi {:info {:title "my-api"
 :description "reitit + openapi3"
 :version "0.0.1"}
 :tags [{:name "api"
 :description "the api"}]}
 :handler (openapi/create-openapi-handler)}}]

 ["/api"
 {:tags ["api"]}

 ["/hello"
 {:get {:summary "hello"
 :handler (fn [_]
 {:status 200
 :body "hello world"})}}]

 ["/plus"
 {:post {:summary "plus with malli body parameters"
 :description "description here"
 :parameters {:body {:x :int, :y :int}}
 :responses {200 {:body {:total :int}}}
 :handler (fn [request]
 (let [{:keys [x y]} (-> request :parameters :body)]
 {:status 200
 :body {:total (+ x y)}}))}}]]]
```

Here's what
[Swagger UI](https://swagger.io/tools/swagger-ui/)
looks like for this API:

<img src="../../img/posts/reitit-openapi-swagger-ui.png">

The
[ring-malli-swagger](https://github.com/metosin/reitit/tree/master/examples/ring-malli-swagger)
and
[ring-spec-swagger](https://github.com/metosin/reitit/tree/master/examples/ring-spec-swagger)
examples in the Reitit repository has been extended to serve OpenAPI 3
& Swagger specs side-by-side. Check them out!

## Migrating A Reitit App to OpenAPI 3

Just like in the previous example, you can easily serve Swagger and
OpenAPI 3 specs side-by-side for a transition period.

To migrate your Reitit app to OpenAPI 3, do the following:

1. Add a `reitit.openapi/create-openapi-handler` route. Here's a minimal example:
```clj
["/openapi.json"
 {:get {:handler (openapi/create-openapi-handler)
 :openapi {:info {:title "my nice api" :version "0.0.1"}}
 :no-doc true}}]
```
2. See how your OpenAPI 3 spec looks like in Swagger UI, and validate
 it using a tool like
 [openapi-schema-validator](https://www.npmjs.com/package/@seriousme/openapi-schema-validator).
3. If you have additional fields under your swagger handler (e.g.
 `:securityDefinitions`), port them to OpenAPI 3 format, and add
 them under the `:openapi` key in the route you just added.
4. If you have custom `:swagger` data on your other routes, convert
 them to `:openapi`
5. Use `:json-schema/default` and `:json-schema/example` in addition
 to `:swagger/default` and `:swagger/example` in your schema metadata.
 - For Plumatic Schema, the new keys are `:openapi/default` and
 `:openapi/example` instead.

## Thanks

It takes a village to raise a library, as they say. I'd like to thank
everybody who made this Reitit update happen.

First of all, thanks to [Solita](https://www.solita.fi) for sponsoring
the delivery of the OpenAPI 3 feature and thus my part of the work.
Without their nudging and financial support, this release would've
happened a _lot_ later.

Secondly, thanks to current and former Metosin programmers
[@ikitommi](https://github.com/ikitommi),
[@Deraen](https://github.com/Deraen),
[@kalekale](https://github.com/kalekale), and
[@miikka](https://github.com/miikka)
for their work on the Metosin libraries
[Reitit](https://github.com/metosin/reitit),
[Malli](https://github.com/metosin/malli),
[Spec-tools](https://github.com/metosin/spec-tools), and
[Schema-tools](https://github.com/metosin/schema-tools).

The foundation of the work was transforming Malli, Spec and Plumatic
Schema schemas into [JSON Schema](https://json-schema.org/), which
OpenAPI 3 builds on.

The initial JSON Schema support for Spec (via spec-tools) and Malli
was implemented by Metosin.

[@rrudakov](https://github.com/rrudakov) contributed OpenAPI support for spec-tools in
[PR #236](https://github.com/metosin/spec-tools/pull/236)
and schema-tools in
[PR #63](https://github.com/metosin/schema-tools/pull/63).

Bringing all of these tools together in Reitit was a long process,
with lots of discussion among the community in
[Reitit issue #84](https://github.com/metosin/reitit/issues/84)
and some valiant first implementation efforts by
[@czan](https://github.com/czan) and
[@Koura](https://github.com/Koura).

Finally, things started to come together last fall when
[@souenzzo](https://github.com/souenzzo)
(from [CyCognito](https://www.cycognito.com/))
submitted an initial version of OpenAPI 3 support in
[Reitit PR #563](https://github.com/metosin/reitit/pull/563)

I picked their work up this spring, added some missing pieces like
docs, tests, and coercion and
[multipart uploads](https://github.com/metosin/reitit/issues/591).

Finally, I wanted to make sure we support mutual recursion of schemas
properly. Luckily,
[@cap10morgan](https://github.com/cap10morgan)
was working on some fixes related to that
[on the Swagger side](https://github.com/metosin/malli/issues/464),
so we could help each other.
[Malli issue #868](https://github.com/metosin/malli/issues/868)
tracks all the fixes I made.

**A big thank you to everybody!**

. Please test it and report any problems on 

. We'll have a proper 0.7.0 release soon!

OpenAPI 3 Support for Reitit

A month ago I gave my first meetup talk ever. For those who are thinking of
doing this or have been there know it’s not necessarily easy to make the
decision to go talk to a bunch of seasoned programmers about _any_ topic. The
bar definitely feels high even when it shouldn’t be.

At the end of October, my colleague invited me to talk about this curious side
project of mine in a Clojure meetup that would be held in Oulu, in the northern
half of Finland. Little wonder as I'd been blabbering about my side project
during friday coffee sessions, demoing it to colleagues, and thus had gathered
interest in the topic. I slept on the decision and ended up accepting the
invitation.

The meetup was set to be held on December 1st and was hosted by the kind
[Enhancell](https://enhancell.com/) folks within their cozy office premises in
the heart of Oulu city.

## Clock starts ticking

<img src="../../img/posts/clojure-meetup-oulu-2022-onmyway.jpg" style="width:100%;">

The countdown began with four weeks on the clock. I decided on my title right
after receiving the invitation. For me, it was important to have an explicit
title so that the contents of that talk would be clear beforehand and potential
guests could make their RSVP decisions more easily. The title of my talk was:

> Creating an experimental GraphQL formatter using Clojure, Instaparse, and GraalVM. 

I knew I had to put some buzzwords in there, so I put all of them there. Some
old, some new - all good, as they say!

At end of the week, I started preparing my presentation at a high-level using
markdown Gist and bullet points. This allowed me to create the _narrative_
without spending too much time on the graphics, typography, demo code, and
other embellishments at this point. Crafting the bullet points took me one
friday evening.

## Three weeks left

At this point, I still had ample amount of time to get things right. Yes, even
my editor code style schemes.

But I still had to get my bullet points right as I knew my draft was still very
rough. I spent the entire next week fixing all my typos, bending the narrative
to my will, and thinking about the lessons in all of this. This retrospective
process involved going through the code and commits from the beginning and
reflecting on my feelings about the problem/solution space, and also digging up
my notes on different experiments and reflecting on those.

Another week began, and I already knew I had to start fleshing out my slides.
The sand was sifting through the hourglass and I didn't have any memes on my
powerpoint yet. 

And to add to my bikeshed woes, no way people would be reading markdown Gist
with enhanced grandpa font sizing (if only I had enough time to learn emacs org
mode)! Where were those company slide templates again? Which template was the
least stale out of the three?

Pretty soon I would have to start throwing that clay into something far more
beautiful. So that's what I started doing. 

At the end of the week, I had something that I could call "graphical" (in lieu
of a better word). I also wrote some [demo
code](https://github.com/ilmoraunio/graphqlfmt-clj-experiment/blob/meetup-demo/demo/evolution_of_the_ast.clj)
to showcase parts from the Abstract Syntax Tree processing pipeline that I had
built for my formatter, and then continued working on my slides, spit-polishing
the graphical parts, making sure I was using the right font sizes consistently
everywhere, etc. You know, the _important_ stuff.

## Final week: the hustle edition

On the final week, I solely focused on presentation notes, refining both the
content of the slides and rehearsing what my notes would sound like when I
actually presented it.

My goal was to aim for a maximum of 20-to-30 minutes which I thought would be a
good meetup talk length. I basically adjusted this to the time we had in total
and the number of talks we would have, plus adding into the consideration the
fact that people probably wanted to socialise as well.

Being on stage can make you forget ALL kinds of lines, improvised or not. It
was very important to write those notes down. For me, this was extra important
as I have a habit of forgetting a lot of words and things when under stress.

Initially, I’d set myself the goal not to improvise too much during rehearsal.
I only did it during times when I really couldn’t come up with anything that I
could write down in my notes. If something good came up during practise, I
would write that down. Repeat ad nauseam.

My final rehearsal in the hotel room before the meetup was strictly on-script
only with **very** minor changes to my slides and presentation notes. Also,
before the presentation, I added some very quick and small amendments to the
notes. Nothing too fundamental.

## Stepping into the fray

<img src="../../img/posts/clojure-meetup-oulu-2022-intro.jpg" style="width:100%;">

I already knew well in advance that I couldn't _just_ read from the script. I
would have to up the ad-libbing during the actual talk to make it more
interesting for the crowd.

In fact, when I watched **Jarppe Länsiö**, a Metosin colleague of mine, present
the **Architect’s Case** where he explained the architectural rationale for
selecting Clojure I became more confident of my decision. His talk was a tour
de force and contained little if any notes (or any that I saw at least). He
made it _appear_ as if he had improvised the whole talk. It was fun and
engaging, not least because of its blitzy tempo but also because some new war
stories were shared.

After Jarppe's talk, it was my turn to talk. While I’d clocked my presentation
during rehearsals to stop somewhere during the 20-to-30-minute mark, my actual
talk took me 43 minutes! And with the after-discussion I went well beyond
overtime, clocking in at 50 minutes.

<img src="../../img/posts/clojure-meetup-oulu-2022-ilmo.jpg" style="width:100%;">
Me, tuning the ad-lib to 11

The presentation itself went without major problems and there were some
questions during the presentation as well as after the presentation. There were
also a couple moments where I struggled a bit in trying to explain the concept
of Instaparse in a beginner-friendly way. Something I had not planned in my
notes. I also didn't expect that there would be people who hadn't really done
much with Clojure, but I probably should have!

## Show must go on

Besides these two presentations, we also heard from **Martín Varela** about his
historical path towards Clojure from the academic world and his current work
where he’d, among other things, produced a whitepaper pinpointing anomaly
events in logs from stability testing using N-grams or Deep-Learning as part of
his normal day-to-day programming work. This was insightful and also gave me
some ideas on how to leverage something like this, only simpler, for structured
logging data as well (something which the whitepaper did not focus on
primarily).

<img src="../../img/posts/clojure-meetup-oulu-2022-martin.jpg" style="width:100%;">
Martin Varela, opening up on the perceived difficulties of ze parentheses

All in all, the Clojure Meetup Oulu was really nice with friendly people from
diverse backgrounds. The guests had really good questions throughout the
presentations and they seemed to have enjoyed their time there! The hosts were
also super nice to us even when we went slightly overtime.

And finally, let’s not forget the second most important bit here. The food. We
had vegan and gluten-free pizza for all plus inclusive drinking options.

After the meetup, we switched locations to discuss on the meetup topics but
also other programming-related topics such as emacs and technical metal. All in
all, what a blast!

## Reflection

If you’ve never held a talk at a meetup before, I warmly recommend doing so as
it’s a great experience. It’s not necessary to set a high bar for yourself or
strive for perfection nor do you need to write code for as long as I did. 

All talks will be different and interesting in their own way, both in terms of
content but also presentation style. The most important part is that you feel
you want to talk about it.

For me, this was a unique and inclusive first-time experience. I definitely
encourage everyone to try it out once you’ve reached a certain level of
comfortability to start blabbering about something in front of a small crowd. :-)

 
<hr />

_Here is the link to my presentation slides:
https://www.slideshare.net/metosin/creating-an-experimental-graphql-formatter-using-clojure-instaparse-and-graalvm_

_And also, if you’d like to join our company where we focus on all things
Clojure (be it meetups, [naked-performance
programming](https://www.youtube.com/watch?v=3SSHjKT3ZmA), or Clojure
consulting), let’s start talking: rekry@metosin.fi_

My First Meetup Talk

## best viewed using curl

The year 2012 was a significant year for Metosin; for more than one reason. In addition to starting the company operations in January 2012, we also started an important new project for our client using Clojure. At the time, this was quite a controversial decision. The general consensus at the time was that proper software projects were always done using Java and Spring framework.

The project turned out to be a major success for our customer, but in 2012 this was in no way inevitable. One critical risk in our decision to use Clojure was the availability of skilled Clojure programmers.

In May 2012 I and my colleague and co-conspirator Tommi Reiman attended the very first EuroClojure in London (the original site is long gone, but thanks to the Wayback machine, we can find it [here](https://web.archive.org/web/20120412175506/http://euroclojure.com/2012/)). We were thrilled to hear the presentations and meet many great Clojure luminaries like Zach Tellman, Stuart Halloway, Christophe Grand, Malcolm Sparks, Rich Hickey, and many more. The community around Clojure was vibrant, energetic, and amazingly welcoming for total newbies like us.

On our way home, we were convinced we needed to organize a small get-together focused on Clojure in Finland. We hoped to bootstrap the Clojure community in Finland with the same energy and friendliness we witnessed in London. Maybe this would help give Clojure more visibility and reduce the risk of not having enough skilled Clojure programmers.

## oct 4th note: full house

Clojure conference we must have, this much was clear.

We needed speakers, preferably from abroad, to give our conference a glorious international feeling. We told our CEO, Mikko Heikkilä, to figure this out: "There's no hurry; you have two weeks". Mikko contacted Bruce Durling, who had just given a presentation in EuroClojure.

Unfortunately, Bruce could not make it, but he promised to help us by using his contacts in the London Clojure community.

This worked well, and very soon, Sam Aaron contacted Mikko and told him that he had never been to Finland and would like to give a presentation about the Clojure interactive programming for generating music. Soon we also had confirmations from the local software industry; Lasse Rasinen from Zenrobotics and Markku Rontu from NitorCreations agreed to give presentations.

So this is happening. We need a web page.

<div>
 <img src="/img/posts/clojutre-2012-02.png">
 
 ClojuTRE 2012 web-page
 
</div>

The web page for ClojuTRE was quickly hacked together by yours truly. In hindsight, it's hard to say if the limiting factor for the aesthetic aspects of the page were the lack of time, lack of skill, or the general absence of taste. The most likely combination of all three.

## towels included

Our principal motivation was to bring together people who share our enthusiasm for Clojure to talk, share ideas, and, since this is Finland, have a few beers and enjoy the sauna.

We understood that most of the interested people don't use Clojure in their work and would most likely be unable to get financial support from their employers. So, a free conference it is.

Fortunately, we got NitorCreations to sponsor the conference and share the bill. The bill was not very impressive; the venue for 25 persons, sauna, few beers and pizzas, travel and hotel for Sam, we're not talking big bucks here.

The Friday 12th of October 2012 was at hand much sooner than we realized. After hectic last-minute errands, the first ClojuTRE was in progress.

<div>
 <img src="/img/posts/clojutre-2012-01.jpg">
 
 Sam setting up his presentation in ClojuTRE 2012
 
</div>

It was informative; it was inspirational, and, most importantly, it was fun. After the presentations, we had pizza, beer, and a sauna. Sam enjoyed the sauna a lot.

Unlike Sam, Christophe Grand had a different opinion of the whole sauna experience. Next year, in connection with ClojuTRE 2013, we organized a public Clojure training with Christophe, Sam, and Meikel Brandmeyer as teachers. After the event we had, again, pizza, a few beers and sauna. Christophe reported to his friends back in France about our _"attempt to steam-cook him alive"_. Guess sauna is not for everyone.

With a new project, ClojuTRE, and the training, the year 2012 was quite busy for Metosin. When the year was ending, we started to make plans for 2013. One thing was clear; _"We need to do this ClojuTRE thing again."_

<div>
 <img src="/img/posts/clojutre-2014-01.jpg">
 
 Meikel Brandmeyer preparing for ClojuTRE 2014 in Metosin HQ
 
</div>

## programming as a form of communication

Fast-forward seven years, and we get to ClojuTRE 2019. What started in 2012 as a low-key, ad hoc get-together for 25 local Clojure programmers had grown to a two-day international conference with ~400 attendees each day. In 2019 we had more speakers than we had attendees in 2012!

<div>
 <img src="/img/posts/clojutre-2018-3.jpg">
 
 ClojuTRE goes Helsinki, 2018
 
</div>

Although the size of ClojuTRE was different, we wanted to maintain the sense of homegrown, down-to-earth, warm personal feeling of the first ClojuTRE. That meant we needed to find a way to source the arrangements for some other company. This meant that we (and I mean mostly Mikko here) spent a lot of time making ClojuTRE the event we wanted.

Even with the generous support from our sponsors and 75€ ticket price, the financial impact of ClojuTRE was no longer a footnote in accounting for a small software consulting. The expenses were over 70k€, even without counting all the hours our people put into this.

Don't get me wrong; we have benefitted from ClojuTRE greatly. Although we have not emphasized our role as the organizer and instead promoted the community as a whole, ClojuTRE has given us a lot of visibility and a good reputation far more significant than any marketing effort could have ever accomplished.

Still, from a purely financial point of view, ClojuTRE had become really expensive for us. However, we felt that ClojuTRE was more important than just us or money; we were doing something we were really proud of.

It seems that people liked the concept and the execution: Here's some feedback we have had over the years.

<blockquote class="bq-1">The conference was very well organised. One of the best organisations I've seen, as a matter of fact</blockquote>

<blockquote class="bq-2">Fantastic conference guys! Truly top drawer stuff. Top name speakers, good venue, free food and drink and all for 0€ - amazing. I just can't compliment you enough! :)</blockquote>

<blockquote class="bq-1">ClojuTRE is the best conference I have attended. Love to all the people organizing it &lt;3</blockquote>

Many people have liked the short talks:

<blockquote class="bq-2">The event was very well organised. What a splendid idea to keep presentations short – the pace of it worked great for preventing sleep throughout the day!</blockquote>

<blockquote class="bq-1">I think you guys pretty much nailed the format and execution for the perfect conference. ClojuTre has definitely become my favourite conf.</blockquote>

<blockquote class="bq-2">Top notch organization of the conference, the venue and food was pretty amazing.</blockquote>

The quality of presentations and the variance of topics has also been well received:

<blockquote class="bq-1">Atmosphere was great as it has been every year since 2012. Good mix of talks with different kind of topics and seriosity</blockquote>

<blockquote class="bq-2">Exceptional speakers! Absolutely fabulous set of topics in talks. It covered very wide area and opened my eyes</blockquote>

<blockquote class="bq-1">I loved Clojutre, and it is by far the most excellent technical conference I have ever been to, from the atmosphere and spirit, to the quality and topic range of talks</blockquote>

Friendly, open, and welcoming atmosphere has been our top priority right from the start.

<blockquote class="bq-2">A wonderful conference with a very friendly atmosphere</blockquote>

<blockquote class="bq-1">I love that you care about diversity and inclusion! And thank you for the great event, can't wait until next year!</blockquote>

I guess something from our local culture has given the event a bit of flavor:

<blockquote class="bq-2">Thank you arranging Clojutre. It is a fantastic conference that I will be recommending to all Clojurists I meet. Don't give into any pressure to change the concept and your special Finish approach</blockquote>

<blockquote class="bq-1">It was amazing, and Finland rocks – thank you for the work you put in!</blockquote>

## not finnish? or from Turku?

Right after the 2019 event, the ClojuTRE 2020 planning kicked in full swing.

Then Covid-19 happened, and all plans were trashed. Suddenly nobody was able to make any commitments to travel anywhere in any time soon. So ClojuTRE 2020 was postponed, then again in 2021, and yet still in 2022.

Now we're in the final stages of 2022 and starting to look at 2023. Although the shadow of the pandemic seems to be lifted, the world's safety and financial situation is far from certain. The outrageous war with senseless destruction and murder of civilians in Ukraine has put the whole continent on uneven footing. With a future that can be described as uncertain at best, what should a small company with a big dream do?

Organizing ClojuTRE requires a lot of work, money, and commitment. We want to maintain the idea and the soul of ClojuTRE, and at this time we're not ready to make the commitment that ClojuTRE deserves.

So, with a heavy heart, I must pronounce yet another postponement for ClojuTRE.

## bring your laptop

While our beloved conference is in a deep sleep at R'lyeh, we're not going to be idle. We hope to serve the local community best by helping to organize a set of small Clojure meetups throughout 2023. In fact, we already started the Oulu Clojure meetup just last week. That is part of our super secret plan to open an office in Oulu, but more about that later.

Another thing we're committed to is our continued efforts on open-source projects, ours and others too. Check out the [latest blog posts by Tommi](https://www.metosin.fi/blog/transforming-data-with-malli-and-meander/) and [Juho](https://www.metosin.fi/blog/reagent-towards-react-18/). Tommi will probably write more about that soon, so stay tuned.

## obsessed with programming

So what's with the weird heading captions?

If you figure it out, let me know at Clojurians slack, I go by handle `@jarppe`. The first person to do so wins a ticket to the next ClojuTRE, whenever that happens!

Story of ClojuTRE from 2012 to 2019, and beyond...


This Christmas, I want to gift you something practical. Something
useful. None of that [artsy nonsense](https://www.metosin.fi/blog/christmas-card/)
from last year.

[Here it is!](https://github.com/opqdonut/hash-f) Feel free to open
the link before Christmas Day.

Merry Christmas!


A Christmas Present in Clojure

Related posts

OpenAPI 3 Support for Reitit

My First Meetup Talk

Story of ClojuTRE from 2012 to 2019, and beyond...

Contact