Skip to content

Collecting API Documentation

Tommi Reiman edited this page Mar 1, 2015 · 2 revisions

Collecting API Documentation

Swagger 2.0

Swagger defines a JSON Schema for presenting the web api documentation. To be more Clojure-friendly, ring-swagger provides a Prismatic Schema presentation of that Schema, the ring.swagger.swagger2-schema/Swagger and a conversion utilities to transform the data into valid Swagger JSON Schema form.

Steps

  1. Write code that collects the api routes, input & output data models and other metadata into the defined schema form & validate the results against the Swagger-schema.
  1. Create handlers for the needed Swagger artifacts:
  • You need to serve swagger.json via ring.swagger.swagger2/swagger-json: consumes the Swagger-schema data and outputs Swagger JSON Schema form
  • (optionally) One can also server packaged swagger-ui via ring.swagger.ui/swagger-ui (the ring handler) or ring-swagger.ui/wrap-swagger-ui (middleware)
  1. Verify that the generated Swagger JSON validates against the Swagger JSON Schema (the Swagger Schema is NOT 100% representation of the JSON Schema, just a pragmatic loose subset of it)
  • TODO Publish the embedded JSON Schema Validator for this
  • See the samples
  1. Publish you new adapter

  2. Pull Request to list your adapter here and in the swagger-spec pages

Swagger 1.2

The old spec, with separate Resource listing and Api declarations.

Example adapter found in the fnhouse-swagger project.

Need help?

If you need help in adoption, open on issue on GitHub, or ping us directly (mention ring-swagger at #clojure on Freenode or email to [email protected])

Clone this wiki locally