Documentation driven testing

[nomasprime]

We're documenting our schema with PRMD and it's working much better for us than Swagger, thank you.

My questions are:

1. How can I reuse JSON-API schema in PRMD to document the API? I'd like to use JSON-API definitions at a top level and then override them for our specific implementation.
2. How can the docs be used to drive tests in RSpec?
3. As the docs provide a general case for each end-point, how can I test given a specific context?

[geemus]

Hey, glad it's working well for you.

1. I'm afraid I don't quite follow the question, maybe you could provide a more concrete example to help me get on the same page?
2. For testing, I'd recommend interagent/committee, which has test helpers.
3. Could you provide an example for this one as well.

Thanks!
wes

[nomasprime]

Currently have the JSON-API schema in meta.json and want to reuse in each resource to DRY things up. Bashing my head against a wall, any help would be much appreciated 😄

https://gist.github.com/habitullence/ee674ea5bddbfe21f3d6e3e402e6871f

[nomasprime]

I've updated with an example of trying, and failing, to overwrite type. I'll be looking to overwrite attributes in a more realistic example.

[nomasprime]

allOf is the way to go according to https://spacetelescope.github.io/understanding-json-schema/structuring.html but unfortunately I get:

Error in resource: assessment-assignments
rake aborted!
NoMethodError: undefined method `include?' for nil:NilClass
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schemata/helper.erb:169:in `build_attribute'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schemata/helper.erb:70:in `block in extract_attributes'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schemata/helper.erb:7:in `each'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schemata/helper.erb:7:in `extract_attributes'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schemata.md.erb:27:in `result'
/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `eval'
/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `result'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schema.erb:8:in `block in result'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schema.erb:4:in `map'
/bundle/gems/prmd-0.12.0/lib/prmd/templates/schema.erb:4:in `result'
/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `eval'
/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `result'
/bundle/gems/prmd-0.12.0/lib/prmd/core/renderer.rb:49:in `render'
/bundle/gems/prmd-0.12.0/lib/prmd/commands/render.rb:34:in `render'
/bundle/gems/prmd-0.12.0/lib/prmd/rake_tasks/doc.rb:54:in `render_file'
/bundle/gems/prmd-0.12.0/lib/prmd/rake_tasks/doc.rb:63:in `render_to_file'
/bundle/gems/prmd-0.12.0/lib/prmd/rake_tasks/doc.rb:80:in `block (2 levels) in define'
/bundle/gems/prmd-0.12.0/lib/prmd/rake_tasks/doc.rb:79:in `each'
/bundle/gems/prmd-0.12.0/lib/prmd/rake_tasks/doc.rb:79:in `block in define'
/service/lib/tasks/prmd.rake:25:in `block in <top (required)>'
/bundle/gems/rake-12.0.0/exe/rake:27:in `<top (required)>'
Tasks: TOP => schema:doc

[nomasprime]

Looks like this has come up before: #163

[nomasprime]

@geemus is there anything else I can do to help resolve this?

From the related issue, it looks like I might not be able to reuse the JSON-API schema.

[geemus]

Sorry for the delay, I'm not sure. It probably ought to work in theory, but I'm not certain exactly where it goes off the rails in practice. It's not something I have bandwidth to really dig into deeper at the moment, but I'm happy to support you however I can if you would like to dig deeper.