search

interagent / prmd

JSON Schema tools and doc generation for HTTP APIs
MIT License
2.1k stars 172 forks source link

Documentation driven testing #322

Open nomasprime opened 7 years ago

nomasprime commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

Looks like this has come up before: https://github.com/interagent/prmd/pull/163

nomasprime commented 7 years ago

@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 commented 7 years ago

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.