populating swagger description from schema docstring

[murtaza52]

Hi,

I have defined my schemas using defschema and have given them docstrings. When generating the swagger json, I dont see the docstring being extracted.

The swagger spec provides a :description key, is it possible to populate that key using the docstring for a given schema ?

Thanks,
Murtaza

[ikitommi]

Hi,

Yes, we should use that. There is already support for it in schema-tools (https://github.com/metosin/schema-tools/blob/master/src/schema_tools/core.cljc#L246-L255), but ring-swagger doesn't use that yet. Would you like to integrate that in?

[murtaza52]

Sure would like to give it a shot. Which function should I look at in
ring-swagger to begin with ?

On Tue, Dec 1, 2015 at 8:38 PM, Tommi Reiman [email protected]
wrote:

Hi,

Yes, we should use that. There is already support for it in schema-tools (
https://github.com/metosin/schema-tools/blob/master/src/schema_tools/core.cljc#L246-L255),
but ring-swagger doesn't use that yet. Would you like to integrate that in?

—
Reply to this email directly or view it on GitHub
#76 (comment)
.

[lyderichti59]

Hi,
I've written my own wrapper of schema.core/defschema to have the same feature.
Sharing here just in case it inspires someone :)

(defmacro defschema
  "Same as `s/defschema` but adds docstring as swagger's schema description"
  [name docstring form]
  `(s/defschema ~name ~(str docstring)
     (vary-meta ~form assoc-in [:json-schema :description] ~docstring)))

[kevinkrouse]

I think this is possible, if not a little awkward:

(s/defschema PhoneRecord
  (rsjs/describe
    {:phone (rsjs/describe s/Str "The phone number")
     (s/optional-key :label) (rsjs/describe s/Str "An optional label")}
    "Contact phone record"
    :example {:phone "555-1212" :label "Mobile"}))

generates:

    "PhoneRecord" : {
      "description" : "Contact phone number",
      "example" : {
        "phone" : "555-1212",
        "label" : "Mobile"
      },
      "type" : "object",
      "properties" : {
        "phone" : {
          "description" : "The phone number",
          "type" : "string"
        },
        "label" : {
          "description" : "An optional label",
          "type" : "string"
        }
      },
      "additionalProperties" : false,
      "required" : [ "phone" ]
    }