I'm using compojure-api 2.0.0-alpha19, spec-tools 0.6.1, and trying to
generate swagger pages with :spec coercion in compojure-api.
I know this is a work in progress but I'm not an expert in any of these
tools and thought I'd ask here before I write pesky and likely incorrect
issues in the Metosin repos. I've done a fair bit of prismatic-schema
enabled compojure-api and so was trying to translate some of that into a
spec-ized implementation. However i've either made a ton of mistakes
(quite likely), or there's a lot of bugs, I'm not sure.
The following code fragments and annotated image show some of the problems
I'm seeing. Advice welcome.
Basic specs, later aliased via 'db-jobs':
(s/def ::job-id nat-int?)
(s/def ::job-type #{:this-job :that-job :the-other-job})
Specs built on the above, later aliased via 'specs' in compojure-api
declarations:
(s/def ::job-id
(st/spec ::db-jobs/job-id
{:description "Specifies a Job ID, must be accompanied by a Firm
ID for any valid use."}))
(s/def ::job-type
(st/spec ::db-jobs/job-type
{:description "Specifies the type of job to be dispatched to a
suitable worker service node."}))
(s/def ::firm-id
(st/spec nat-int?
{:description "Specifies a Firm ID in the service database, or
zero if there there is no specific firm."}))
Compojure-api code using the above three specs:
...
(:require
[clojure.spec.alpha :as s]
[compojure.api.core :as api-core]
[compojure.api.sweet :as sweet]
[compojure.route :as route]
[my.specs :as specs]
[spec-tools.core :as st]
...
(sweet/defroutes routes
(sweet/POST "/job/:firm-id" []
{:summary "Enqueue a job"
:description "Enqueue a job."
:path-params [firm-id :- ::specs/firm-id]
:body-params [job-type :- ::specs/job-type]
:responses {201 {:description "Job enqueued." :schema ::specs/job-id}
400 {:description "Invalid job type."
:schema (st/spec string? {:description "Value of
the unsupported job-type argument."})
}}}
{:status 201 :body (impl/create-job! firm-id job-type)}))
...
(sweet/api
{:coercion :spec
:swagger {:data {;;:basePath "/"
:info {:title "Job Scheduler"
:description "Jobs"
:version 1
:contact {:name "Pizza Eaters Inc." ...}}}
:ui "/docs/swagger"
:spec "/docs/swagger.json"
:options {:ui {:docExpansion "list"}}}}
The resulting swagger page (fragment) follows, annotated for discussion:
<https://lh3.googleusercontent.com/-caIoOltcD_s/WvnkJRmrGDI/AAAAAAAAMnc/8DGLbjWPqr4kAWh1i2kFN976fWwCZNAOACLcBGAs/s1600/swagger2.png>
1. For the Response Class presentation, it would be nice to get the
description shown with the ::job-id type.
2. The 'job-type' parameter name is not shown.
3. The description of the 'job-type' parameter is not shown.
4. The 201 response code data is missing from Response messages.
5. (not highlighted) :firm-id works as expected, whether it's because
it's a :path-param or because it lacks the same degree of indirection in
its spec definition I don't know.
Also note that
:path-params [firm-id :- (sweet/describe ::specs/firm-id "Firm identifier,
or zero if there is no firm.")]
Does not produce a description in swagger, however the spec.tools code in
the initial compojure-api code I presented works. Bug or feature? (Seems
like sweet/describe might be deprecated as we move to clojure.spec if we're
using spec-tools).
Anyway, tips appreciated, and patience for obvious "user" mistakes.
--
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
---
You received this message because you are subscribed to the Google Groups
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
