Notes, possibly unhinged, about the state of RSwag.

General

• We’ve tried to be respectful of existing PRs by not making too many changes that would introduce merge conflicts. I think with the v3+v3.1 revisions we’ll want to temporarily dump that policy to give a full cleanup of the project so we can get the ball rolling again.

Housekeeping

• ToDo: Add security scanners to CI process
  • bundle-audit
  • brakeman
• Rubocop is installed but there are hundreds of offenses
  • The majority of them are autocorrectable but people have been holding off because of merge conflicts
  • ToDo: .github/workflows/rubocop.yml
  • ToDo: use $ rubocop --auto-gen-config to generate a TODO of all the stuff that cannot be safely autocorrected
• ToDo: rename branch main to master to match modern conventions
• ToDo: Github Discussions seem to have gone quiet. Close them?
• ToDo: The wiki seem to have gone quiet. Close it?
• ToDo: CodeClimate integration seems busted. Fix It.

Contribution experience

• It’d be nice to have a “project structure” section in CONTRIBUTING.md to get people oriented
• docker-compose.yml is there for running the app but it’s not apparent what’s going on
• Has a Makefile, a Dockerfile, and ci/build.sh
  • Why three different ways of setting up?
  • The usage of docker isn’t really documented
  • Suggestion: use Makefile as canonical source for all development scripts Include instructions on how to set up bash autocomplete in shell
    • make build
    • make lint
    • make format
    • make test
      • make test:unit
      • make test:e2e
    • make start
    • make audit
    • End-to-end testing seems to be minimal
      • ToDo: Add playwright for cross-browser tests?
• Requires both Node and Ruby; only one is specified via .ruby-version
  • Switch to asdf? It covers multiple runtimes and allows for multiple different versions to accommodate maintainers on different versions (eg. ruby 3.0.7 3.1.4 3.2.1 # etc...

Code & Issues Review

• Removal of support for OAS 2 has been going slowly due to lack of contributors but Roman is getting close on it 🎉
• There’s quite a few spots that I could see benefitting from some light refactoring to make the project more approachable
• A lot of the questions that come through are from using the testing setup in ways that are very different
  • Suggestion: Add a generator for a recommended spec structure $ rails g rswag:suite What is the root of your api routes? (/api): ___ … \\specs \\openapi \\api \\users GET_spec.rb POST_spec.rb \\__id__ GET_spec.rb POST_spec.rb DELETE_spec.rb Ideally we can hook it up to rails routes to generate the structure based on the actual routes and methods.
• The test-app directory has a very basic setup.
  • We could make more use of it as a sample application to point users towards for common cases that are currently filling up the README.md
  • E2E tests could then verify that all these common use cases continue to function across.
  • ToDo: Investigate what I’d take to deploy the sample app for users to play with