[PATCH 01/17] REST: Add additional documentation

[Daniel Axtens]

Stephen Finucane <stephen at that.guru> writes:

> As noted in the Django REST Framework docs [1], views that support
> multiple methods can and should split their documentation using
> 'method:' style delimiters. Do just this.
>
> [1] https://www.django-rest-framework.org/topics/documenting-your-api/#documenting-your-views
>
> Signed-off-by: Stephen Finucane <stephen at that.guru>
> ---
>  patchwork/api/check.py   |  8 +++++++-
>  patchwork/api/index.py   |  1 +
>  patchwork/api/patch.py   | 10 +++++++++-
>  patchwork/api/project.py | 11 ++++++++++-
>  patchwork/api/user.py    | 11 ++++++++++-
>  5 files changed, 37 insertions(+), 4 deletions(-)
>
> diff --git a/patchwork/api/check.py b/patchwork/api/check.py
> index 48019e72..4771455f 100644
> --- a/patchwork/api/check.py
> +++ b/patchwork/api/check.py
> @@ -74,7 +74,13 @@ class CheckMixin(object):
>  
>  
>  class CheckListCreate(CheckMixin, ListCreateAPIView):
> -    """List or create checks."""
> +    """
> +    get:
> +    List checks.
> +
> +    post:
> +    Create a check.
> +    """
>  
>      lookup_url_kwarg = 'patch_id'
>      ordering = 'id'
> diff --git a/patchwork/api/index.py b/patchwork/api/index.py
> index 2266635c..45485c91 100644
> --- a/patchwork/api/index.py
> +++ b/patchwork/api/index.py
> @@ -11,6 +11,7 @@ from rest_framework.views import APIView
>  class IndexView(APIView):
>  
>      def get(self, request, *args, **kwargs):
> +        """List API resources."""
>          return Response({
>              'projects': reverse('api-project-list', request=request),
>              'users': reverse('api-user-list', request=request),
> diff --git a/patchwork/api/patch.py b/patchwork/api/patch.py
> index 6367dd5d..523378da 100644
> --- a/patchwork/api/patch.py
> +++ b/patchwork/api/patch.py
> @@ -188,8 +188,16 @@ class PatchList(ListAPIView):
>  
>  
>  class PatchDetail(RetrieveUpdateAPIView):
> -    """Show a patch."""
> +    """
> +    get:
> +    Show a patch.
> +
> +    patch:
> +    Update a patch.
>  
> +    put:
> +    Update a patch.
I thought put created a patch/project/person. Does it also serve to
update one? I know we got an issue via the mailing list about put vs
update; should the docs make the distinction a bit clearer?

Apart from that, LGTM.

Regards,
Daniel

> +    """
>      permission_classes = (PatchworkPermission,)
>      serializer_class = PatchDetailSerializer
>  
> diff --git a/patchwork/api/project.py b/patchwork/api/project.py
> index 22fb1c4e..d7bb1f21 100644
> --- a/patchwork/api/project.py
> +++ b/patchwork/api/project.py
> @@ -74,6 +74,15 @@ class ProjectList(ProjectMixin, ListAPIView):
>  
>  
>  class ProjectDetail(ProjectMixin, RetrieveUpdateAPIView):
> -    """Show a project."""
> +    """
> +    get:
> +    Show a project.
> +
> +    patch:
> +    Update a project.
> +
> +    put:
> +    Update a project.
> +    """
>  
>      pass
> diff --git a/patchwork/api/user.py b/patchwork/api/user.py
> index e11bed4b..29944e22 100644
> --- a/patchwork/api/user.py
> +++ b/patchwork/api/user.py
> @@ -48,6 +48,15 @@ class UserList(UserMixin, ListAPIView):
>  
>  
>  class UserDetail(UserMixin, RetrieveUpdateAPIView):
> -    """Show a user."""
> +    """
> +    get:
> +    Show a user.
> +
> +    patch:
> +    Update a user.
> +
> +    put:
> +    Update a user.
> +    """
>  
>      pass
> -- 
> 2.17.2
>
> _______________________________________________
> Patchwork mailing list
> Patchwork at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork