square/fdoc — pull request #11 by chris-baynes (2012-08-29 13:58:09+00:00)
Title: URL params checking and documenting.

I've opened this issue to start a discussion on better handling for url parameters. This isn't finished code (though it works right now for our use case), but I'm happy to adjust it and improve given some feedback. This was previously mentioned in #6 but here's some more detail.

The idea is to separate request parameters from url parameters. A simple example is for resources - what you can do with the submitted change is the following:

```ruby
describe "#show", :fdoc => "users/user" do
get user_path(:id => 5)
end
```

```yaml
---
# fdoc/users/user/user.fdoc.resource
description: User id
type: integer
example: 5
# optional fields...
# display_name: user_id
# name: user_key
```

When running the spec, fdoc will see that there is a resource file in that path and then know that the ```user``` part of the path should be dynamic. The generated html will now show two more things:

* The displayed url will be ```/users/:id```
* There will be a url params section which shows the details from the user resource file.

Finally, a couple of other features:

* If resources are nested, then only the final one will be using ```:id```, the others will use the containing directory name suffixed with ```_id```
* The ```name``` field in the resource file is an override in cases when the url param is not a rails resource, and is a plain url param (eg country_code)
* The ```display_name``` field is how the field will appear in the html documentation. The spec will be run against ```name``` (or ```id``` if this does not exist), but usually it's more useful to refer to this as something else in the documentation.

Some things currently missing from the integration:

* Scaffolding support (you must create the resource files manually)
* Tests

Let me know what you think. I think this is a really useful feature and hope it can be integrated.