From patchwork Tue Oct 30 11:19:00 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 990730 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 42kptc3gcLz9s7T for ; Tue, 30 Oct 2018 22:20:56 +1100 (AEDT) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="K1IpaOl9"; dkim-atps=neutral Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 42kptc2167zDrPq for ; Tue, 30 Oct 2018 22:20:56 +1100 (AEDT) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: lists.ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="K1IpaOl9"; dkim-atps=neutral X-Original-To: patchwork@lists.ozlabs.org Delivered-To: patchwork@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=none (mailfrom) smtp.mailfrom=that.guru (client-ip=185.234.75.18; helo=relay018.mxrelay.co; envelope-from=stephen@that.guru; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: lists.ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="K1IpaOl9"; dkim-atps=neutral Received: from relay018.mxrelay.co (relay018.mxrelay.co [185.234.75.18]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 42kpsT5QqDzDrPq for ; Tue, 30 Oct 2018 22:19:57 +1100 (AEDT) Received: from filter002.mxroute.com (unknown [185.133.192.179]) by relay018.mxrelay.co (Postfix) with ESMTP id 2156A4056E for ; Tue, 30 Oct 2018 11:19:24 +0000 (UTC) Received: from one.mxroute.com (one.mxroute.com [195.201.59.211]) by filter002.mxroute.com (Postfix) with ESMTPS id E5FC53F547 for ; Tue, 30 Oct 2018 11:19:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=kpX+C3vZ53Pu2CGoOp/JNipAe5LYmqPd9mQ8piZ4Uk8=; b=K1IpaOl9YPDCNMfwSdHcH9kxTD zyRn90DA376URqAzF5YPje3pnj1TsfaYLPKcsFGPR1AMLvK1h5eXdGuUcor6xNjLlMUFn8eSOUSid SV+o0y6lOmB99I1bp6kCFIYXPUCCo/L36qVPZvnckmCO8etEELtlykcfaFaIFD7rMT+HN1rBItyaj 8aa/gEKLknYwQ29Kj+OjbS0y1jU1sEQOUouPtQ1CVXRlAsMXnzav9OyZPAv05Ac+IOOmUa7ot+JGR Cfe6DG1+ormAsRui61f/RCnOUryj9Al7skDn4h0TvkKL58tY70Hg5zJj5rI7VgmJEoozKp1GyVqFq fmxXzVQw==; From: Stephen Finucane To: patchwork@lists.ozlabs.org Subject: [PATCH 01/17] REST: Add additional documentation Date: Tue, 30 Oct 2018 11:19:00 +0000 Message-Id: <20181030111916.7342-2-stephen@that.guru> X-Mailer: git-send-email 2.17.2 In-Reply-To: <20181030111916.7342-1-stephen@that.guru> References: <20181030111916.7342-1-stephen@that.guru> X-AuthUser: stephen@that.guru X-BeenThere: patchwork@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Patchwork development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: patchwork-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Patchwork" 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 --- 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. + """ 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