Draft: POC Grape to rswag converter (!204430) · Merge requests · GitLab.org / GitLab

What does this MR do and why?

Rswag is a rails gem that generates openapi specs from rswag dsl rspec tests. This MR adds a conversion class that can generate rswag specs from existing Grape API definitions/endpoints and the entities they expose. These specs can then be "swaggerized" through a built in rswag rake task to generate robust openApi 3+ documentation.

This POC handles most of what we would need to convert our existing grape api classes to openapi specs.

The Code in this MR

The main attraction is the GrapeToRSwag converter class

The following generated rswag specs are also included:

What the converter class in this MR covers:

parsing existing class to generate a spec in spec/requests/rswag/<api_class_name>_spec.rb
organizes routes by path
identifies and parses url/path_params and query_params and request_params
includes type(handles oneOf types as well), description, format, defaults, examples
generates response body based on route_entity
includes all defined failure responses

What's Missing & Challenges

does not handle authentication or authorization
does not handle nested response entities
I did not fully configure rswag to it's full potential. Everything is pretty much out of box rswag installation from the rake task installer
I think the converter could be developed more fully to cover everything and anything we would need to write full request specs
How will we handle CE vs EE endpoints
there are several API classes that define routes for other endpoints (ie award_emojis), how will we handle these?
How will we handle versioning our api?? currently if a request is made to v3 an error is returned but when you parse grape apis the path has a url param :version in it
Some APIs have dynamic values or responses based on procs or dynamically generated code example:
- API::Environments where there is a default value set to a proc default: -> (30.days.ago)

How could we leverage this approach in our journey to OpenAPI3?

rswag is currently well maintained gem providing seemless OpenApi 3+ spec generation and will likely remain so
shifting to rswag would allow for bi-directional API development (specs/docs first then Grape apis implemented from those specs)
A converter class could be used and re-used in a few ways:
- intially to generate rswag specs from existing endpoints
- we could still use existing request specs in parallell while offering evolving openapi3 specs
- once all existing grape APIs are converted, this generator class could be used as developer tooling (ie. a dev writes a new grape api or adds to one - all they would need to do is run the converter class to generate a new or update an old spec, speeding up development time and also ensuring that the new endpoint meets the requirements of our API)
- if we ever want to update our API in other ways, like say return other content types, the generator would make it easy to add another response type

References

How to set up and validate locally

In order to see this tool in action + the generated specs + API documentation there are 2 steps!

Convert an Existing Grape API to an rswag friendly request spec:

Switch to this branch && Open a rails console bundle exec rails c
Pick 1 or more API classes to convert (found in: lip/api/) note: the POC I have built can only handle one class at a time
Use the converter to generate 1 or more rswag specs:

  #API::Events can be replaced with any of the api classes

  pry>> GrapeToRswag.new(API::Events).convert_to_spec

===> 
  #The output includes the spec code generated and the file path of the newly (re)generated spec
  #all the rswag specs are generated to a folder `spec/requests/rswag` by default

Generate OpenApi Docs

In your terminal/bash run bundle exec rake rswag:specs:swaggerize PATTERN="spec/requests/rswag/**/*_spec.rb"
This will generate a fresh swagger/v1/swagger.yaml (used for the swagger docs)
Navigate to http://gdk.test:3000/api-docs (or however your local instance is configured)
Observe the generated documentation
You can also check out the openapi3 spec at http://gdk.test:3000/api-docs/v1/swagger.yaml