Adding API Support to Packwerk for Modular Rails Using Rswag: Has Anyone Tried It?

Tools
1

This message was imported from the Ruby/Rails Modularity Slack server. Find more info in the import thread.

Has anyone using Packwerk for modular Rails tried adding a pack supporting an API, and documented/tested that using rswag ?

2

Message originally sent by slack user U71QAKHHQEE

We are actually getting ready to do this. Let us know if it goes well for you!

3

So far, its working.

4

Message originally sent by slack user U71QAKHHQEE

Nice! So you’re writing rswag tests and generating the OpenAPI Spec from them?

5

I had to put a swagger_helper in the root spec folder, and have it call a function from my pack to get the top-level config I wanted NOT to be globally specified… :disappointed:

6

Well, docs are generating.

7

Message originally sent by slack user U71QAKHHQEE

yeah, I have a feeling we are going to have some of that

8

(along with models)

9

Message originally sent by slack user U71QAKHHQEE

Well, docs are generating. that’s a great start at least haha

10

Message originally sent by slack user U71QAKHHQEE

Glad to hear it’s working!

11

I put this in my pack’s lib directory:

require 'yaml'

module V3APISwaggerDocHelper
  def self.swagger_docs
    {
      'v1/swagger.yaml' => {
        openapi: '3.0.3',
        info: {
          title: 'SSP API for v3',
          description: 'Supply Side Platform API to enable capabilities delivered via cooperation of 2 systems.',
          version: 'v1'
        },
        paths: {},
        components: {
          securitySchemes: {
            basicAuth: {
              type: 'http',
              scheme: 'basic'
            }
          },
          schemas: schema_models
        },
        # security: [
        #   { basicAuth: [] }
        # ],
        servers: [
          {
            url: 'https://{defaultHost}/api/v1',
            variables: {
              defaultHost: {
                default: '[www.example.com](http://www.example.com)'
              }
            }
          }
        ]
      }
    }
  end

  def self.model_files
    ['api_types', 'events', 'models'].flat_map {|subdir| Dir["#{__dir__}/schemas/#{subdir}/*.yml"]}
  end

  def self.schema_models
    model_files.reduce({}) do |schema_hash, filename|
      schema_id = File.basename(filename, '.yml').camelize
      schema_payload = YAML.load_file(filename)
      schema_hash[schema_id] = schema_payload
      schema_hash
    end
  end
end
12

And I call that from the root swagger_helper

13

Then, I put all the YAML component schemas I want to reference under lib , either in events , models or api_types

14

Message originally sent by slack user U71QAKHHQEE

I see, so your devs are managing .yml files the majority of the time and you’re generating code from those?

15

The yml is for the re-usable types… could use JSON, too…

16

rswag allows those to be blended together with endpoint definitions.

17

Message originally sent by slack user U71QAKHHQEE

:+1: got it

18 
RSpec.describe 'Buyer API' do

  path '/buyers' do

    get 'Retrieve SSP buyers' do
      tags 'buyers'
      produces 'application/json'
      parameter name: :id,
                required: false,
                description: 'filter to only include the buyer with matching ID',
                in: :query,
                schema: { '$ref' => '#/components/schemas/BuyerId' }
      
      response '200', 'retrieve list' do
19

(using that BuyerId component)

20

Message originally sent by slack user U71QAKHHQEE

makes sense. did you look into just being able to write ActiveModels and directly reference those? My plan was to attempt something along those lines (most likely adding a to_swagger to each active model implementation or something like that, not sure).

I hadn’t considered going pure yml but that may be even better all things considered - we’ve slowly piecing together what we want our main entity models to look like long term