search

interagent / prmd

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

Exceptions getting started #291

Open mafrosis opened 8 years ago

mafrosis commented 8 years ago

Calling prmd init without an argument causes an exception:

$ prmd init
/usr/local/bundle/gems/prmd-0.11.7/lib/prmd/templates/init_resource.json.erb:3:in `result': undefined method `capitalize' for nil:NilClass (NoMethodError)
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `eval'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `result'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/core/generator.rb:19:in `generate'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/commands/init.rb:47:in `init'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/cli/generate.rb:43:in `execute'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/cli/base.rb:141:in `run'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/cli.rb:97:in `run'
    from /usr/local/bundle/gems/prmd-0.11.7/bin/prmd:6:in `<top (required)>'
    from /usr/local/bundle/bin/prmd:22:in `load'
    from /usr/local/bundle/bin/prmd:22:in `<main>'

Then trying to generate docs from a schema, it seems that character encoding is not being handled correctly:

$ prmd doc /schema/approve_schema.json
Error in resource: name
/usr/local/bundle/gems/erubis-2.7.0/lib/erubis/converter.rb:132:in `scan': invalid byte sequence in US-ASCII (ArgumentError)
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/converter.rb:132:in `convert_input'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/converter.rb:36:in `convert'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/engine.rb:30:in `initialize'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/template.rb:45:in `new'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/template.rb:45:in `load'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/template.rb:54:in `load_template'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/template.rb:64:in `render'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/templates/schemata.md.erb:2:in `result'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `eval'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `result'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/templates/schema.erb:7:in `block in result'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/templates/schema.erb:4:in `each'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/templates/schema.erb:4:in `map'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/templates/schema.erb:4:in `result'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `eval'
    from /usr/local/bundle/gems/erubis-2.7.0/lib/erubis/evaluator.rb:65:in `result'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/core/renderer.rb:49:in `render'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/commands/render.rb:34:in `render'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/cli/doc.rb:65:in `execute'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/cli/base.rb:141:in `run'
    from /usr/local/bundle/gems/prmd-0.11.7/lib/prmd/cli.rb:95:in `run'
    from /usr/local/bundle/gems/prmd-0.11.7/bin/prmd:6:in `<top (required)>'
    from /usr/local/bundle/bin/prmd:22:in `load'
    from /usr/local/bundle/bin/prmd:22:in `<main>'
geemus commented 8 years ago

Hmm. I think maybe that init is expected to have an argument always, though that is certainly not a very helpful error message.

I'm less certain about the encoding issue, do you have non-ascii in that schema? Could you share the schema that is causing the issue so I can work on debugging against it? Thanks!

mafrosis commented 8 years ago

@geemus Yah I guessed there should be some validation on the init command :)

Here's a breaking JSON schema: I used curl to pull down the gist, and still see the exception above:

https://gist.github.com/mafrosis/edb462ad16d05ce695c7c8018a2d1971

geemus commented 8 years ago

It may be a ruby version thing. I'm seeing an error as well, but not the same one. I think one key thing to note is that the schema you doc is expected to have gone through combine (which makes a sort of uber-schema). If you haven't combined the individual schema, doc gets confused because things are not in the places it would expect. So, I think for you it will work better if you for instance do something like:

prmd combine /schema/approve_schema.json | prmd doc

(you can also pipe the output to a file and then doc that instead of piping).

That gives me:

Meta is empty, please fill it next time.
## <a name="resource-approve_schema.json">portal_approve</a>

A description

### Attributes

| Name | Type | Description | Example |
| ------- | ------- | ------- | ------- |
| **email** | *string* | An email address | `"example"` |
| **link** | *string* | DEPRECATED. A link for the user to follow to change password | `"example"` |
| **name** | *string* | The contact's full name | `"example"` |
| **token** | *string* | The password change token (previously part of link) | `"example"` |

You can clear up the meta part by init-ing a meta file (which has top level info like the host for the API and name).

Hope that clears some things up, the error you were getting was definitely not helpful whatsoever (as unfortunately many erubis/template errors tend to be). I also got an error there, but it was at least nominally clearer (it was a no split method on nil error, guessing your error also results from a nil where a character string is expected). Anyway, I'm not sure about how to make that error better in particular, but hopefully this can help you workaround it.