Docs DB

database.yaml

# database tables schema
tables: 
  # "Guide" rows will be created with data from swagger, we can have rake task that loads data from swagger after deploy
  # we shoulda have a uniq validation of [slug, vertion] so we can select/display diferent version for a guide.
  # need to figure out how to index the guides nested in a way that makes it possible to find guides based on resources and endpoints
  guides: we search in this level...
    description: 'bla bla bla...' #swagger.info.description # 
    title: 'Salesforce' #swagger.info.title
    slug: 'sobject' #id of the swagger config
    version: '1.0.0' # swagger.info.version # 1.0.0
    definitions: {} # virtual attribute to get data.swagger.definitions without loading the whole swagger
    data: # jsonb data
      swagger: {} # should we store the parsed swagger doc in the db? If we do so we can persist old versions and allow updates

  # "Resource" rows will come from the parsed Swagger::Resources lib, a guide can have many resources, 
  # this records are also used to create the resources navbar.
  swagger_resources:
    guide_id: 1 # belongs to guide
    title: 'ProcessInstance' # x_resource
    slug: 'process-instance' # slugified x_resource
    description: 'comes from somewhere' # this is not available on the swagger file, we may need to pull from somewhere else
    data: # jsonb
      endpoints: [...] # we can try keep the endpoints denormalized

  # [MAYBE] if need to normalize the data we can create the tables bellow but ideally we wont need to that
  # swagger_endpoints:
  #  resource_id: 1
  #  data: {
  #    path,
  #    method,
  #    ... everything else from endpoint
  #  }
  #
  #  swagger_paramemters:
  #    endpoint_id: 2
  #    data: {}
  #
  #  swagger_definitions:
  #    resource_id: 1
  #    data: {}

@3den If we name resources swagger_resources, then guides should be swagger_guides?

Not sure I've thought this through, but here it goes...

The search_data (searchkick) can be at swagger_resource level and you can index data from associations

#swagger_resources

def search_data
{
  title: title,
  description: description,
  guide_title: guide.title
  guide_description: guide.description
  etc
}

For definitions, a def can be used in several endpoints and an endpoint can have several defs. So a join table would be used between endpoints and defs. But also, can a def be used anywhere (not just in an endpoint)?

I believe swagger parameters are specific to the endpoint they are in. Its not like a parameter can be used in 2 different endpoints. Sure the type of a param can be re-used (but thats a defenition) but the params are order-specific and I dont think need to be shared amongst endpoints and would be unwise to normalize this further. Now, whether we put them in a spearate table oir not is up for debate as a separate table makes it more clear and allows us to expand the columns we keep for a parameter without modifying the endpoint table o thats a good idea. Of course jsonb works the same too. But I think a separate table is more clear and easy to read and makes it explicit what columns we expect from a parameter.

version in guides is the version we read from swagger righjt. So for sobject that will be something like 30.0 (i.e., not the swagger version but the API's version)?

So is guides:data:swagger just storing the actual original yml file? For posterity?

RE: jsonb versus a new table for definitions, endpoints and parameters: I think the guiding force is do we need to keep unstructured data around? I believe that we have a formal structure and we need to rely on that formal structure and that structure comes from 2 sides... first side is swagger itself and the other side is our Ruby objects and rendering code rely on specific fields being available. thus we have very structured data and would benefit by declaring this (formally) in the form of tables and not allowing it to be non-schema'd.

Regarding search: I think we must be able to search on endpoints, parameters as well as guide (descriptions) and resources (such a poor word to use here). So we should be indexing all of that.

I envision a cool "advanced" search where I can say something like I want those endpoints which have a Date parameter type (oor have a parameter named chochootrain. I see this as a useful way to find stuff when you kind-of remember what you are looking for but not the whole thing (i.e, I recall theres a parameter names choochootrain somewhere and thats the one I want to locate).

@shyam i was thinking that we would need to define the search_data on Guide instead of resources coz the search happens there. Also our search is a bit more complicated than that coz we nest on also on endpoints and its parameters...