interagent/prmd — pull request #161 by jasonrudolph (2014-09-07 23:38:46+00:00)
Title: Fix error generating docs when "anyOf" defines schemas for a property

Fixes #160.

@geemus: Thanks for [pointing me toward to a fix](https://github.com/interagent/prmd/issues/160#issuecomment-54753071) for this issue. :zap: I think this pull request will do the trick.

d920d29a74ac93ea3667a0b5c51c30ea4252ea2a introduces a rudimentary smoke test for `Prmd#render`. It essentially verifies that `Prmd#render` successfully produces Markdown for the given schema. It's not a comprehensive test by any means, but it at least lets us know that `Prmd#render` didn't throw an exception. Over time, I could see this test growing to assert more specific results of `Prmd#render`.

Building on the test structure introduced in d920d29a74ac93ea3667a0b5c51c30ea4252ea2a, 33a653bccbce9c2f4b1df4aa186cd3cd16a13a39 adds a test and a fix for #160. After removing the sorting (as suggested in https://github.com/interagent/prmd/issues/160#issuecomment-54753071), I had to make a couple other tweaks to ensure that the docs render successfully. (The commit message describes the details.)

With these commits in place, prmd can now render the docs for the schema referenced in #160. [[output](https://gist.github.com/jasonrudolph/3b70f911a55a070b08c9#file-schema-md)]

Specifically, this part of the schema:

```json
"properties": {
"name": {
"anyOf": [
{ "type": "number", "minimum": 0 },
{ "type": "string", "maxLength": 5 }
]
}
},
```

Leads to this Markdown:

```md
#### Optional Parameters
| Name | Type | Description | Example |
| ------- | ------- | ------- | ------- |
| **name** | *string* | | |
```

Note that the docs only show one of the two types (i.e., just `string`, instead of `string` and `number`). I think this is due to way the type is determined [here](https://github.com/interagent/prmd/blob/87f00fcc1d433231f959aebf25a6dc1a703f685d/lib/prmd/templates/schemata/helper.erb#L109). While it would be nice to have prmd handle multiple types, I think that's a bigger change that affects more than just the use of `anyOf`. So, I think any enhancements in that area should happen in a separate pull request. In the meantime, this pull request allows prmd to gracefully generate docs for more types of schemas (e.g., like the one shown in #160), and that feels like A Good Thing™.