Schema autogeneration

[cecedille1]

Schema Autogeneration

This pull request addresses Schema autogeneration from the API views.

1. it resolves a bug where the higher namespace urls (/account/{account_id}/books/{pk}/) are hidden by lower namespace (/account/{pk}/).
2. It uses the docstring of the method that will handle the request (either get, post, put, etc for the APIView or list, retrieve, update for the viewset) as the description of the coreapi.Link.
3. It uses the help_text of the serializers fields as the description of the coreapi.Field.
4. It capitalize the names of the Link.

[tomchristie]

Great stuff in here, thanks!
Will review shortly.

[tomchristie]

Okay, so there's a number of different aspects here, some we want, some we probably don't, some may need further thought.

1. Yes, we should resolve that, although not 100% clear to me exactly what we should use for the key generation. Needs further thought.
2. Useful, although note that this would also pull in unhelpful docstrings from the default mixin implementations, so not sure how we should best handle that.
3. Yes.
4. Not totally convinced if we should be using Humanized or programatic formatting for the keys.

The path_descriptions API you've added is also perfectly reasonable, tho again, I'm not 100% sure if it's exactly what we want or not.

[kevin-brown]

1. Sounds like an issue, but I can't think of a clean way to resolve them properly. Someone else who has more experience reverse-engineering url patterns can probably chip in here.
2. I'm a fan of this, because I personally have a tendency to write method-specific documentation when I'm overriding them. With that said, I do see the issue that Tom mentioned with the default mixins having developer-oriented documentation instead of user-oriented documentation. I'd personally prefer developer-oriented documentation there, so I don't have a solution.
3. Handled in Add form field descriptions to schemas #4387.
4. Imo, this is better handled client-side. The keys appear to match the url path for links right now, and this change can be done on the client if needed.

[tomchristie]

On second thoughts I noted that the .get etc... methods that we provide in REST framework don't have default docstrings, so we could use them. Although some users will be using base classes and/or mixins where the docstrings may not be correct/relevant, so point still applies, but less so than it would otherwise.

[tomchristie]

• Some remaining work on (1) prior to the 3.4.4 release - still not handling that quite right.
• For (2) I'm happy to reassess that as part of 3.5.0 - happy to see an individual issue opened for it. We're adding in the form field descriptions now. We could also look at addressing path field and query field descriptions.
• 3. Now resolved.
• 4. Going to stay with lowercase for now. We'll firm up the generator API methods and document them as public API, so that folks can introduce third party packages with overrides if wanted.