Input & output validation with api-docs (swagger)

ikitommi commented 7 years ago

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 commented 7 years ago

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

ikitommi commented 7 years ago

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 commented 7 years ago

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

yogthos commented 7 years ago

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

ikitommi commented 7 years ago

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 commented 7 years ago

This is looking very nice. :)

ikitommi commented 6 years ago

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:

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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)

yogthos commented 6 years ago

I'm definitely be interested in taking a go at using Reitit in Macchiato, but I've been a bit swamped lately. If anybody gets around to it before I do, that would be very welcome.

nenadalm commented 5 years ago

I was playing wih Macchiato and Reitit a bit and and here is the result so far: https://github.com/nenadalm/spa-demo.

Swagger with spec coercion, validation works (only with json for now). I intend to do some demo of project with single page app using re-frame, api using Macchiato and server side rendering.

It might take a while with current speed (if ever), but basics with Macchiato and Reitit seems to be working. I hope to use that at work some day :)

yogthos commented 5 years ago

Thanks, that looks great. I keep to switch Macchiato to use Reitit as the default at some point. This will be helpful as a starting point.

ikitommi commented 5 years ago

Awesome!

Just asked about the record walking cljs issue on CLJS Jira, would like to get your spec-tools pr merged.

macchiato-framework / macchiato-core

Input & output validation with api-docs (swagger) #7