feat: KEH-171 enhance API documentation with OpenAPI schemas#593
feat: KEH-171 enhance API documentation with OpenAPI schemas#593
Conversation
pexxi
force-pushed
the
keh-171-add-openapi-spec-generation
branch
5 times, most recently
from
a4d9ff0 to
27d0b7b
Compare
|
KERROKANTASI-API branch is deployed to platta: https://kerrokantasi-pr593.api.dev.hel.ninja 🚀🚀🚀 |
This should not probably happen if the PR is in draft mode? |
|
KERROKANTASI-API branch is deployed to platta: https://kerrokantasi-pr593.api.dev.hel.ninja 🚀🚀🚀 |
1 similar comment
|
KERROKANTASI-API branch is deployed to platta: https://kerrokantasi-pr593.api.dev.hel.ninja 🚀🚀🚀 |
pexxi
force-pushed
the
keh-171-add-openapi-spec-generation
branch
from
e07e68c to
bc2826f
Compare
|
KERROKANTASI-API branch is deployed to platta: https://kerrokantasi-pr593.api.dev.hel.ninja 🚀🚀🚀 |
|
KERROKANTASI-API branch is deployed to platta: https://kerrokantasi-pr593.api.dev.hel.ninja 🚀🚀🚀 |
- Added new dependencies `drf-spectacular` and `PyYAML`. - Enhanced various viewsets in the democracy app with OpenAPI schema annotations for better API documentation. Ref: KEH-171
pexxi
force-pushed
the
keh-171-add-openapi-spec-generation
branch
from
49a2db7 to
96bfc95
Compare
|
|
KERROKANTASI-API branch is deployed to platta: https://kerrokantasi-pr593.api.dev.hel.ninja 🚀🚀🚀 |
There was a problem hiding this comment.
I started to ponder is this something we want here in the repository 🤔
To me it mostly looks like a one-timer
|
Looks a OK to me. Let's chat about the prompt and then merge 🚀 |
| # ============================================================================ | ||
| # Pagination Parameters | ||
| # ============================================================================ | ||
|
|
||
| PAGINATION_PARAMS = [ | ||
| OpenApiParameter( | ||
| "limit", | ||
| OpenApiTypes.INT, | ||
| description="Number of results per page", | ||
| ), | ||
| OpenApiParameter( | ||
| "offset", | ||
| OpenApiTypes.INT, | ||
| description="Offset for pagination", | ||
| ), | ||
| ] |
There was a problem hiding this comment.
These are not needed, they generated automatically by drf-spectacular.
| ORDERING_PARAM = [ | ||
| OpenApiParameter( | ||
| "ordering", | ||
| OpenApiTypes.STR, | ||
| description="Sort field (prefix - for descending order)", | ||
| ), | ||
| ] |
There was a problem hiding this comment.
This is not needed, equivalent ordering documentation is generated automatically by drf-spectacular.
However, the automatically generated ordering documentation doesn't seem to include the fields that can be used for ordering, so more specific descriptions that include the fields, like HEARING_ORDERING_PARAM are still a good idea.
| # ============================================================================ | ||
| # Root-Level Comment Filter Parameters | ||
| # ============================================================================ | ||
|
|
||
| ROOT_COMMENT_FILTER_PARAMS = [ | ||
| OpenApiParameter( | ||
| "hearing", | ||
| OpenApiTypes.STR, | ||
| description="Filter by hearing ID", | ||
| ), | ||
| OpenApiParameter( | ||
| "section", | ||
| OpenApiTypes.STR, | ||
| description="Filter by section ID", | ||
| ), | ||
| OpenApiParameter( | ||
| "comment", | ||
| OpenApiTypes.STR, | ||
| description="Filter by parent comment ID", | ||
| ), | ||
| OpenApiParameter( | ||
| "label", | ||
| OpenApiTypes.STR, | ||
| description="Filter by label ID", | ||
| ), | ||
| OpenApiParameter( | ||
| "pinned", | ||
| OpenApiTypes.BOOL, | ||
| description="Filter for pinned comments", | ||
| ), | ||
| OpenApiParameter( | ||
| "created_by", | ||
| OpenApiTypes.STR, | ||
| description="Filter by creator ('me' for current user)", | ||
| ), | ||
| OpenApiParameter( | ||
| "created_at__lt", | ||
| OpenApiTypes.DATETIME, | ||
| description="Filter comments created before this date", | ||
| ), | ||
| OpenApiParameter( | ||
| "created_at__gt", | ||
| OpenApiTypes.DATETIME, | ||
| description="Filter comments created after this date", | ||
| ), | ||
| ] | ||
|
|
||
| # ============================================================================ | ||
| # Hearing Filter Parameters | ||
| # ============================================================================ | ||
|
|
||
| HEARING_FILTER_PARAMS = [ | ||
| OpenApiParameter( | ||
| "title", | ||
| OpenApiTypes.STR, | ||
| description="Filter by title (case-insensitive contains)", | ||
| ), | ||
| OpenApiParameter( | ||
| "open_at_lte", | ||
| OpenApiTypes.DATETIME, | ||
| description="Filter hearings opening at or before this date", | ||
| ), | ||
| OpenApiParameter( | ||
| "open_at_gt", | ||
| OpenApiTypes.DATETIME, | ||
| description="Filter hearings opening after this date", | ||
| ), | ||
| OpenApiParameter( | ||
| "label", | ||
| OpenApiTypes.STR, | ||
| description="Filter by label ID (comma-separated for multiple)", | ||
| ), | ||
| OpenApiParameter( | ||
| "published", | ||
| OpenApiTypes.BOOL, | ||
| description="Filter by published status", | ||
| ), | ||
| OpenApiParameter( | ||
| "open", | ||
| OpenApiTypes.BOOL, | ||
| description="Filter by open/closed status", | ||
| ), | ||
| OpenApiParameter( | ||
| "following", | ||
| OpenApiTypes.BOOL, | ||
| description="Filter hearings followed by current user", | ||
| ), | ||
| OpenApiParameter( | ||
| "created_by", | ||
| OpenApiTypes.STR, | ||
| description="Filter by creator ('me' for current user or organization name)", | ||
| ), | ||
| ] | ||
|
|
||
| # ============================================================================ | ||
| # Section Filter Parameters | ||
| # ============================================================================ | ||
|
|
||
| SECTION_FILTER_PARAMS = [ | ||
| OpenApiParameter( | ||
| "hearing", | ||
| OpenApiTypes.STR, | ||
| description="Filter by hearing ID", | ||
| ), | ||
| OpenApiParameter( | ||
| "type", | ||
| OpenApiTypes.STR, | ||
| description="Filter by section type identifier", | ||
| ), | ||
| ] | ||
|
|
||
| SECTION_IMAGE_FILTER_PARAMS = [ | ||
| OpenApiParameter( | ||
| "hearing", | ||
| OpenApiTypes.STR, | ||
| description="Filter by hearing ID", | ||
| ), | ||
| OpenApiParameter( | ||
| "section", | ||
| OpenApiTypes.STR, | ||
| description="Filter by section ID", | ||
| ), | ||
| ] | ||
|
|
||
| # ============================================================================ | ||
| # Label Filter Parameters | ||
| # ============================================================================ | ||
|
|
||
| LABEL_FILTER_PARAMS = [ | ||
| OpenApiParameter( | ||
| "label", | ||
| OpenApiTypes.STR, | ||
| description="Filter by label text (case-insensitive contains)", | ||
| ), | ||
| ] |
There was a problem hiding this comment.
Any of these shouldn't be needed, the same descriptions are included as help_texts.
| - Session Authentication for browsable API | ||
| - Anonymous read access for public content | ||
| """, | ||
| "VERSION": "1.0.0", |
There was a problem hiding this comment.
Will this be somehow automatically updated? If not, IMO it would better to set it as None because most probably it won't be updated at all in the future 🙂
| # Pagination | ||
| PAGINATION_PARAMS = [ | ||
| OpenApiParameter("limit", OpenApiTypes.INT, | ||
| description="Results per page"), | ||
| OpenApiParameter("offset", OpenApiTypes.INT, | ||
| description="Offset for pagination"), | ||
| ] |
There was a problem hiding this comment.
I don't think this should be in the prompt because it shouldn't be ever needed (because drf-spectacular generates it automatically).
5 participants
KEH-171 - Enhance API documentation
drf-spectacularandPyYAMLtorequirements.in.Note: This will not yield to a perfect result immediately, but it should come close. There are some custom implementations in this projects where spectacular cannot help out-of-the-box. That's where manual work is needed.
Refs: KEH-171