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: {}

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...