Swagger

Caseflow's Swagger Usage

URL

The Swagger UI for Correspondence is located at /api-docs in all environments.

Yaml files

The Swagger yaml files are located at app/controllers/swagger/.

The following files are auto-generated by rswag commands and it is not recommended to manually change them.

• app/controllers/swagger/v1/swagger.yaml
• app/controllers/swagger/v2/swagger.yaml
• app/controllers/swagger/v3/swagger.yaml

Servers

We use relative urls for the servers properties. This prepends the current environment's url to the server.

See API Server and Base URL for more details.

Authorization

For authorization while the wiki calls it an API Key it is a HTTP authentication schemes because it uses the Authorization header.

See Bearer Authentication for more details.

Gem

We use Rswag as an Engine to handle routing to the Swagger yaml files and the Swagger UI.

Configuration

• config/initializers/rswag_api.rb
  • This is used when generating the spec file for a controller via rails generate rspec:swagger API::MyController
• config/initializers/rswag_ui.rb
  • This is used for rendering the Swagger UI
  • Each openapi_endpoint listed is a definition that will show up at /api-docs
• spec/swagger_helper.rb
  • This is used when generating the spec file for a controller via rails generate rspec:swagger API::MyController
  • This is used when generating the yaml files for the generated specs via RAILS_ENV=test rails rswag

Swagger

Swagger places API specifications such as OpenAPI, AsyncAPI, and JSON Schema at the core of its architecture, which are crucial for guiding teams through the entire lifecycle of API design and documentation. This strategic focus ensures that our suite, including open source tools and SwaggerHub, delivers unparalleled efficiency and a seamless user experience.

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.

What Is OpenAPI?

rswag

Rswag creates Swagger tooling for Rails API's. Generate beautiful API documentation, including a UI to explore and test operations, directly from your rspec integration tests.