[REQUEST] Support Ruby (WITHOUT RSPEC) OpenAPI specification generation
aka-momo opened this issue · 0 comments
Is your feature request related to a problem? Please describe.
I'm unable to use rswag in my current project which has 35K+ tests. The challenge I'm facing in API documentation is in the reliance on RSpec. Rewriting tests for all APIs is going to be impractical and time-consuming.
Describe the solution you'd like
Implement Ruby-based OpenAPI spec generation in Rswag, independent of RSpec. This would allow us to define API docs using Ruby, streamlining the documentation process for large projects.
What support could we give you, so you could implement this yourself?
Guidance on Rswag's architecture and integration advice for this feature would be helpful. I am willing to contribute to the development of this enhancement.
Describe alternatives you've considered
I've considered some other options , but these lack the integration and ease of use offered by Rswag.
- Manually writing OpenAPI specs
- Using other gems like swagger-blocks (which is not well maintained)
- Build my own gem, which is going to be very similar to rswag. However, it might die in the future without enough contributions like every other swagger gem.
Additional context
This feature would greatly benefit large-scale projects by simplifying API documentation processes. The idea is not to eliminate any of the existing features, I would like to just be able to use the same friendly interface without RSPEC.
Relates to which version of OAS (OpenAPI Specification)
- OAS2
- OAS3
- OAS3.1
Usage Concept Example
# Example: PetsController with Ruby-based API doc definitions
class PetsController
extend Rswag::Helper # A helper module that exposes swagger_path methods
swagger_path '/pets/{id}', version: 'v1' do
get do
# Endpoint details
end
put do # Same rswag logic/syntax excluding running tests
summary 'Update an existing pet'
description 'Updates a pet in the store with form data'
operationId 'updatePetWithForm'
tags 'pet'
security bearer_auth: []
consumes 'application/x-www-form-urlencoded'
# Form data parameters
param :name, in: :body, type: :string, required: true, description: 'Updated name of the pet',
example: 'Doggo'
param :status, in: :body, type: :string, required: true, description: 'Updated status of the pet',
example: 'available'
response 200, description: 'successful operation' do
schema '$ref' => '#/components/schemas/Pet'
end
response 405, description: 'Invalid input' do
schema '$ref' => '#/components/schemas/Error'
end
end
end
end