Swagger Documentation

[markwoodhall]

This pull request is a first attempt at implementing swagger documentation for the cayenne api, it is not yet fully complete but the basic structure is present for a number of the key endpoints.

Funders

• /funders
• /funders/{id}
• /funders/{id}/works

Journals

• /journals
• /journals/{issn}
• /journals/{issn}/works

Works

• /works
• /works/{doi}
• /works/{doi}/agency
• /works/{doi}/quality

Prefixes

• /prefixes/{prefix}
• /prefixes/{prefix}/works

Members

• /members/
• /members/{id}
• /members/{id}/works

Types

• /types
• /types/{id}
• /types/{id}/works

swagger.json is available at /swagger-docs and the swagger ui is available at /swagger-ui.

The following things still need to be finished:

• [x] Facets
• [x] Field queries
• [x] Markup, perhaps directly pulling in or referencing existing rest-api-docs

There are also a number of other endpoint categories that have lower priority and are yet to be documented:

1. cores
2. licenses
3. styles
4. locales
5. reverse

[markwoodhall]

If you want a quick way to test this out you can browse to http://petstore.swagger.io/ and enter https://gist.githubusercontent.com/markwoodhall/11e977324668f48bfa24bdd3841b09c6/raw/d06a7e1010abfcdfc91c517b5a1c87f69918f499/swagger.json in the "Explore" text box at the top of the page.

That url is gist containing the swagger.json generated by ring-swagger.

[afandian]

Looks great! We'll need to see how easy it is to use in this format, and whether we want to pull out the filter text so it only appears in one place in a future iteration.

The Swagger UI will be available at /v1/swagger-ui/.