ring-swagger

ring-swagger & compojure-api
hawari 2017-12-28T03:01:12.000091Z

Hi @wontheone1, since compojure-api built on top compojure, and with that, ring, any valid ring response map will suffice.

{:status 204
 :headers {}
 :body ""}
You might want to learn more about it here https://github.com/ring-clojure/ring/wiki/Concepts

ikitommi 2017-12-28T08:37:40.000160Z

hi @wontheone1, back from the holidays, good that you have mostly resolved all the issues. Does it work if you just use empty map as the response schema? eg. {http-status/created {}

ikitommi 2017-12-28T08:38:38.000157Z

and you can use s/Any as the Schema, for “anything”. Not exactly what you want, but works.

ikitommi 2017-12-28T08:40:49.000101Z

the :compojure.api.meta/serializable? true is internal stuff, marking that the response should be encoded (to support encoding of primitives). I think the encoder should remove it as it’s not useful info outside of c-api. But, you can ignore it.

wontheone1 2017-12-28T14:53:58.000355Z

@hawari.rahman17 Yes; I know how to construct ring response with map but my question was about how do you define schema for response with no body for Swagger. Thank you. I see @ikitommi suggested workaround for my problem below !

ikitommi 2017-12-28T14:55:17.000091Z

… and meant {http-status/created {:schema s/Any}}

wontheone1 2017-12-28T14:58:28.000024Z

@ikitommi Thanks s/Any or {} works ! I am confused, I could swear I tried the empty map and it didn't work yesterday but it's working now

wontheone1 2017-12-28T14:58:40.000293Z

I proly did something wrong yesterday elsewhere

wontheone1 2017-12-28T14:59:46.000172Z

I think for the new users, this kind of cases might be not so obvious, so some examples might help... If you agree I might submit PR for some examples or README improvement

wontheone1 2017-12-28T15:07:02.000280Z

@ikitommi I can easily find out how to generate swagger.json, and expose it with compojure-api but found nothing about it from https://github.com/metosin/ring-swagger. Is similar thing supported? (I mean if you have Swagger definition in clojure map then of course you can generate json/yaml with some library and write using io and stuff but I just assumed this is common case and ring-swagger might as well do all the chores for us)

ikitommi 2017-12-28T15:13:50.000142Z

Just expose the result of ring.swagger.swagger2/swagger2 function. If you need JSON String, run cheshire.core/generate-string to it.

wontheone1 2017-12-28T15:19:25.000380Z

@ikitommi you mean the swagger-json function? result is plain clojure map I think. So putting that in JSON and exposing it as Swagger UI is the work of library user? I got it thanks

wontheone1 2017-12-28T15:20:37.000232Z

I just thought (similar to compojure-api) there would be automagical way to exposing it to Swagger UI. but nevermind

wontheone1 2017-12-28T15:27:39.000116Z

I have a few points about compojure-api library, please consider when you have time. I see there is get-spec function used in tests. https://github.com/metosin/compojure-api/blob/4b5e2f8e59ddb915f70b5e75f70a25ea20f142b0/test/compojure/api/sweet_test.clj#L104 I think we can include this function as one of core library function so that compojure-api user can also easily test the validity of their definitions as in https://github.com/metosin/compojure-api/blob/4b5e2f8e59ddb915f70b5e75f70a25ea20f142b0/test/compojure/api/sweet_test.clj#L211

wontheone1 2017-12-28T15:29:55.000112Z

Using existing function here, https://github.com/metosin/compojure-api/blob/4b5e2f8e59ddb915f70b5e75f70a25ea20f142b0/test/compojure/api/test_utils.clj#L131 to core library, might be enough. If you think this would help, I could try to submit a PR too.

wontheone1 2017-12-28T15:50:49.000266Z

@ikitommi no Thanks for pointing out !! after seeing test-util get-spec is used I thought there was no way 😄... Documentation could be improved on this one too

ikitommi 2017-12-28T15:51:20.000236Z

doc PRs would be most welcome :)

ikitommi 2017-12-28T15:51:51.000268Z

(a whole new static doc site would be super)

wontheone1 2017-12-28T15:56:40.000111Z

I will see what I can do thanks! sorry for spamming the chat, but last thing I want to ask. with value of :responses being a map, there is no duplication of key allowed. so If you want to have 2 (or more) different schemas for the same status code how do you solve it? of course s/Any or anything that accepts all schemas would work. But in the Swagger UI you cannot show them as different responses.

wontheone1 2017-12-28T15:58:52.000161Z

I don't know having different schema with same status code is really bad thing and I would avoid it when possible but just think there might be some cases that would need to do like that. if responses can have a vector as a value, then this will be solved easily. For example :responses [201 {:schema A] 201 {:schema B}]

wontheone1 2017-12-28T15:59:51.000228Z

Not urgent issue anyway as in most APIs, one status code will have one schema, but I wanted to discuss if you think this makes sense anyway @ikitommi

ikitommi 2017-12-28T18:17:17.000216Z

Sadly, Swagger2 doesn’t support anyOf (see https://github.com/OAI/OpenAPI-Specification/issues/57), but you use something like s/cond-pre or use a abstract schema to desribe that in Clojure. The api-docs won’t show that, but if you send correct data over the wire, the Schema Validation approves it. c-api also supports clojure.spec where you can use something like s/or. OpenApi3 supports this, but haven’t had time to implement that. There are issues in ring-swagger, schema-tools & spec-tools if someone has time to implement those. And, all questions welcome 🙂

wontheone1 2017-12-28T19:01:14.000225Z

Aha ! sad history ! thanks for kind answers!

wontheone1 2017-12-28T20:34:32.000049Z

I made a PR to improve docs, please checkout when you have free time.