Collecting API Documentation

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.

• Check out the samples
• See also real sample adapter from fnhouse-swagger with tests

2. 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)

3. 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

3. Publish you new adapter

4. 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])