Story #2335
closed
As an API consumer, I am able to discover filterable fields.
0%
Description
In chatting with asmacdo about his filterset PR for Repository[0], we were lamenting the lack of discoverability of the filter params. We'd love for autogenerated API clients to be able to know what filter options are allowed on a given view, and also to make sure the filter sets associated with a given API view show up meaningfully in the API docs that we generate.
Related issues
Updated by amacdona@redhat.com about 8 years ago
Not sure if this is the direction we want to go, but I hacked this up yesterday.
Updated by semyers about 8 years ago
This is a poorly defined story, at the moment, because we know that we want to do as little work as possible to create API clients, the exact mechanism for achieving that goal has not yet been determined. Under the assumption that whatever mechanism we choose has the ability to express available URL query parameters for a given view, I think using the current OpenAPI standard (v2.0[0]) as a guide is reasonable.
To that end, OpenAPI supports documenting available query params on endpoints:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object
So, we could potentially augment the existing openapi schema codec generator[1] to make DRF include valid query params that our filter sets provide.
As far as documentation goes, that might do well as a separate story, but I'm not sure. asmacdo's approach in the previous comment is a great step in this direction, though.
[0]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
[1]: https://github.com/core-api/python-openapi-codec
Updated by amacdona@redhat.com about 6 years ago
- Is duplicate of Issue #3635: Improve filter documentation by creating a BaseFilterSet class to automatically set filter help text added
Updated by amacdona@redhat.com about 6 years ago
- Status changed from NEW to CLOSED - DUPLICATE
.