Now you only have to include the new action in your routes file and point a swagger-ui (possibly rendered by a standard html-view) at the url.

Usage guide

Providing a schema example

Since the example has to be embedded in the final json/yaml rendering this feature depends on the rendering library you want to use. The extension method is located at swaggerblocks.extensions.<renderinglib>.ExampleExtension. When is is imported, you can call .withExample on the schema definition like shown below:

Caveats

While for the most part the library API tries to stick to the swagger spec, there are some exceptions made either for technical reasons, type-safety or usability:

Since type is a restricted keyword you'll have to use schema in its place. You can use primitive types (e.g. schema = t.string) as well as references to schemas (e.g. schema = petSchema) and it will be sorted out behind the scenes.

Many values in swagger can either be a primitive type, an object or a list of the former two. In order to make this more type-safe and usable, there is a manyOf helper for lists, which accepts primitive types or schemas. Because of type erasure you have to use parameter.manyOf instead of just manyOf for all non-body parameters.

Types are currently namespaced by t (e.g. t.string, t.integer, t.number). Some types should only be used in certain places according to the swagger spec. For example t.file is not allowed in path-parameters, but currently this is not enforced. There are namespaces for the different parameters, so you can easily find the allowed ones using autocompletion (e.g. t.parameter.path.string or t.parameter.formData.file).

The DSL uses a few implicit conversions to provide an easier and more uniform way to write things. For example most optional text fields like description still accept a String literal due to an implicit String => Option[String]. The other conversions deal with differences in schema fields.