documentation

Documentation

Ruby

Ruby projects should use YARD for documentation purposes.

Getting Started with YARD

One benefit is YARD runs a live documentation server for the community, hosting docs for all RubyGems and Github projects. The project is at RubyDoc.info (formerly rdoc.info)

A useful Yardoc cheatsheet

HTTP API

If your project exposes an HTTP API, you should consider documenting the API using the OpenAPI Specification (formerly known as Swagger Specification). The OpenAPI Specification allows for rich description of HTTP APIs—paths, parameters, responses, headers, status codes, etc.—in machine-readable formats.

Specification Formats

OpenAPI Specifications may be expressed as either YAML or JSON. Thus far, we have preferred YAML over JSON because it allows commenting and, unlike JSON, does not care about e.g., trailing commas.

API Documentation Examples

• SDR ("Cocina") Data Models
• SDR Deposit API
• SDR Identifier API
• SDR Indexing API
• SDR Preservation API
• SDR Repository ("DOR Services") API
• SDR Technical Metadata API
• SDR Workflow API (coming soon!)

How To Add OpenAPI To A Project

Here are the steps we have been following:

1. Create openapi.yml: feel free to copy from an existing project, paste, and adjust (example)
2. Validate openapi.yml in the CI build (CircleCI example)
3. Add OpenAPI validation badge to the README (example)
4. Add Committee gem, which allows automagic validation of requests and responses based on your API specification, as a dependency (example)
5. Enable request validation by Committee, then fix all the stuff that breaks as a result of shifting the burden of request validation from your controllers to the Committee middleware (example)
   • NOTE: If request validation causes more breakage than you are prepared to fix, comment out the request validation code and write up a new issue to do this later
6. Enable response validation by Committee, then fix all the stuff that breaks as a result of shifting the burden of response validation from your controllers to the Committee middleware (example)
   • NOTE: If response validation causes more breakage than you are prepared to fix, comment out the response validation code and write up a new issue to do this later
7. Create docs/ folder in the repo and copy the docs/index.html artifact from another repo, e.g., technical-metadata-service, which will parse your OpenAPI specification and generate pretty HTML documentation to be served by Jekyll (via GitHub Pages) in the next step (example)
8. Enable GitHub Pages with the docs/ folder as the source (and don't use the Theme Chooser because docs/index.html already has its own style) in the Settings of the GitHub repository
9. Verify that the automagic OpenAPI documentation works: see examples above
10. Add the GitHub Pages-based OpenAPI URL for your repository (e.g., https://sul-dlss.github.io/suri-rails/) as the "Website" of the GitHub repository