Documentation to non-openapi bootstrap handlers missing

[xificurC]

I can't find a good explanation how should I write my handlers when I'm using martian on something that doesn't provide an openapi schema. Using the petstore and the openapi bootstrap code in martian I came up with these 2 examples:

  (def m (bootstrap "https://petstore.swagger.io/v2"
                    [{:route-name :get-pet
                      :path-parts ["/pet/" :id]
                      :method :get
                      :path-schema {:id schema/Int}
                      }

                     {:route-name :find-pets-by-status
                      :path-parts ["/pet/findByStatus"]
                      :method :get
                      :query-schema {:status schema/Str}
                      }]))

Trying these out they seem to work OK. I can guess my way through all the options I guess (pun intended), but having some docs would make my life easier. Is there none or did I just miss it?

[oliyh]

Hello,

There's a bit in the readme here: https://github.com/oliyh/martian#no-swagger-no-problem

And then the spec here: https://github.com/oliyh/martian/blob/master/core/src/martian/spec.cljc

That covers pretty much everything, I think - I can review and see if anything is missing.

[xificurC]

I read the readme part and didn't know where to put the query parameters. Or that a path part requires a schema (an integer could be inferred). The spec you linked helps, but e.g. what is ::response-schemas?. And the fact that many of them have an ::input-schema doesn't tell me what should I be putting into it.

This isn't exactly a high priority issue though. I'm just letting you know that a new user like me can get a bit lost and needs to read the source code to infer some of the API.

[xificurC]

Another gotcha - I had to debug for a while to find out a :body-schema is required to get a Content-Type header and body in my request. And then a schema of s/Any wasn't enough either because you pull out the first entry from the hashmap and if on that, so I was forced to define at least 1 key in the schema. I have my own malli schemas and don't want to rewrite them into schema just to get martian working. A s/Any schema would work better for me. Also, what if an endpoint's body won't be a map but a list?

[oliyh]

Hello,

Thanks for raising these points. I think a document about these topics would be useful to at least show a full example and discuss the various features.

The 'body destructuring' follows the convention of swagger by having a key or 'name' for the body. There is a test showing the equivalence of forms, including the special :martian.core/body key: https://github.com/oliyh/martian/blob/c20d3fad47709ecfc0493e2fb607d5b56ea3193d/core/test/martian/core_test.cljc#L238

One of the reasons for the 'name' of the body is to support arrays, as shown here: https://github.com/oliyh/martian/blob/c20d3fad47709ecfc0493e2fb607d5b56ea3193d/core/test/martian/core_test.cljc#L245

[xificurC]

I'm coming back to martian in a different project. What idiom would you recommend to use for a :body-schema that is equivalent to an s/Any? I checked the links to sources you posted here but don't see an answer to that. Or would it be possible to include the body and content-type in the request even when there is no schema for it?

[oliyh]

Hi @xificurC

Apologies for not replying to this earlier. Because of the way args need to be supplied for array bodies, it needs a key. You should be able to do the same as demonstrated in this test:

https://github.com/oliyh/martian/blob/master/core/test/martian/core_test.cljc#L300-L312

Hope this helps. I'm going to close this issue, please feel free to reopen if you need it.