Swagger - department-of-veterans-affairs/caseflow GitHub Wiki
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
- This is used when generating the spec file for a controller via
- 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
- This is used when generating the spec file for a controller via
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.
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.