Input & output validation with api-docs (swagger)

[ikitommi]

Optional & pluggable, for handlers, maybe also for middleware. Schema is awesome and proven per today, Spec is the probable future. I could pull out a proposal for a common structure for input & output coercion with api-docs, based on our libs.

• simple, data-driven core
• optionally "easy" macro sugar with inferred models
• pluggable implementation (schema, spec, other)
• protocols for routing libs to collect routes for api-docs
• swagger-docs (ring/spec-swagger)

what do you think?

[yogthos]

Great idea, and makes sense to base it on Metosin libs as they're real world tested already. :)

[ikitommi]

Hi. Finally having time for this. Just talked with @miikka, we will do first drafts of the data-model, for both schema (me) & spec (Miikka). Will integrate the spec-side into the current JVM-based libs too, starting with compojure-api. No plan yet how the code should be split into modules/repos, we'll start with separate code-base(s), let's chat on merging/re-packaging these later.

[ikitommi]

Hi. Drafted some thoughts: https://gist.github.com/ikitommi/fb3e0200504dd8b635ed7edd0cdbc768

[yogthos]

I like your idea of leveraging the metadata for this, and it looks like using Schema or Spec would work nearly identically.

[ikitommi]

The validation part for specs is done'ish, with https://github.com/metosin/spec-tools, I'll write examples on schema & spec -enforced handlers and middleware next.

[yogthos]

This is looking very nice. :)

[ikitommi]

Went few steps back and tried to figure out how to handle the specs/schemas should with (nested) routing like compojure-api does. Ended up writing a small routing library, which supports route meta-data (like middleware & partial route specs/schemas) as first class citizen. Actually quite happy how the lib turned out.

Anyway, about to re-implement the spec/schema validation now, wrote these:

• Support for Swagger/OpenAPI metosin/reitit#19
• Support for request & response coercion (both spec & schema?) metosin/reitit#20

As the coercion is not tied to routing lib and Macchiato uses bidi, might end up spinning a another single-purpose ("just coercion") micro-lib, but will start from there. Targeting anyway Clojure(Script) so should work with Macchiato oob.

[yogthos]

That looks really nice, and Macchiato should allow swapping routing easily. At some point I'm thinking of adding Luminus style profiles, it looks like it should be very easy to swap between Bidi and Reitit.

Out of curiosity, have you had a chance to use Macchiato for anything yet?

[ikitommi]

Sounds great. Have just poked with the samples, no real project for yet. But a new customer project starting next month, going to give it a spin.

[yogthos]

Exciting :) Definitely let me know how things go, also if you'd be interested I can add you to maintainers for the org. Oh wait nevermind, looks like you're already there. :)

[ikitommi]

Coercion is done going forward in reitit, tests run on node, but not tested on actual node-based web server. There are separate modules now for: coercion, spec-coercion and schema-coercion.

Coercion can be applied by using reitit directly + there could be an example how to run this with bidi.

Swagger-docs ~next.

[yogthos]

I'd be open to swapping bidi out for reitit, or adding support for profiles similarly to luminus. I think if reitit will ultimately provide validation and coercion, it would be a better default.

[ikitommi]

Reitit 0.1.0 has shipped, with support for schema & spec coercion for Clojure/Script. 0.1.1-SNAPSHOT has now swagger-support ported also for Clojure/Script!

reitit-examples are for Clojure now, would be good to make a Macchiato example too.

https://github.com/metosin/reitit/blob/master/examples/ring-swagger/src/example/server.clj

Only differences between ring & macchiato at the moment:

• ring.adapter.jetty
• ring.middleware.params/wrap-params
• muuntaja.middleware/wrap-format
• serve swagger-ui somehow

TODO:

• make a Macchiato example (anyone?)
• abstract the differences so that identical apps could be run on both JVM & Node (a separate issue, but thinking aloud)