
[Reitit 0.7.0-alpha1][release] is out now with [OpenAPI 3.1.0 support][docs].
Please test it and report any problems [on Github][issues] or on
the [#reitit channel in Clojurians Slack][slack].
We'll have a proper 0.7.0 release soon!

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
[release]: https://clojars.org/metosin/reitit/versions/0.7.0-alpha1
[docs]: https://github.com/metosin/reitit/blob/master/doc/ring/openapi.md
[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!**


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

<br />
<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


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


```
;;Merry Christmas from
;;Metosin! Run this
;;hand-baked Clojure
;;cookie to find our
;;wish for this holiday
(reduce reduce reduce[,
[reduce[comp][eval,,,,,
replace]][{\e,,,,,,,,,,
(comment)\h,,,,,,,,,,,,
assoc\i,,,,,,,,,,,,,,,,
str},,,,,,,,,,,,,,,,,,,
"herewith""tr,,,,,,,,,,
wdpuocs",,,,,,,,,,,,,,"
reduce"]]),,,,,,,,,,,,,
```


A Christmas Card in Clojure

[@portabletext/react] Unknown block type "undefined", specify a component for it in the `components.types` prop

OpenAPI 3 Support for Reitit

My First Meetup Talk

A Christmas Present in Clojure

Contact