search

square / fdoc

Documentation format and verification
Other
379 stars 59 forks source link

YAML inheritance #53

Open seanpdoyle opened 11 years ago

seanpdoyle commented 11 years ago

Is there any way to DRY up the fdoc response YAML files? I'd love to use something like YAML inheritance, but it doesn't seem to work.

I find myself constantly copy pasting YAMLs across PUT/POST/GET actions

it would be nice to somehow declare a base and have it shared across files

blogPostProperties: &blogPost
  title:
    description: the post title
    required: yes
    type: string
    example: Hello World Post!
  published:
    description: is it published?
    required: yes
    type: boolean
    example: false

Then, elsewhere in (another file) inherit the properties

# fdoc/blogPosts/:id-GET.fdoc
# ...
responseParameters:
  properties:
    blogPost:
      description: the post
      required: true
      type: object
      properties: *blogPost
        # include the base properties, then additionally include some others
        created_at:
          description: the date created
          required: true
          type: date
          example: 'TODAY'
zachmargolis commented 11 years ago

Yes, I totally agree, this is a huge pain point.

Unfortunately, I don't have any good ideas that are extremely clear and easy to explain. The JSON Schema (that we rely on) specifies Canonical dereferencing and inline referencing which may be used to do this, there would need to be a little fdoc sugar to help make these relative to the docs and such.

Like I said I don't have any crystal clear routes to implementing this, but am happy to review & accept pull request.