diff --git a/docs/api/schemas/latest/patchwork.yaml b/docs/api/schemas/latest/patchwork.yaml index 43da55c3..93e56fa0 100644 --- a/docs/api/schemas/latest/patchwork.yaml +++ b/docs/api/schemas/latest/patchwork.yaml @@ -18,6 +18,8 @@ paths: /api: get: summary: List API resources. + description: | + Show paths to all supported API resources. operationId: api_list parameters: [] responses: @@ -32,6 +34,9 @@ paths: /api/bundles: get: summary: List bundles. + description: | + List all bundles that the current user has access to. + For unauthenticated requests, only public bundles can be shown. operationId: bundles_list parameters: - $ref: '#/components/parameters/Page' @@ -75,6 +80,8 @@ paths: - bundles post: summary: Create a bundle. + description: | + Create a new bundle. operationId: bundles_create security: - basicAuth: [] @@ -113,6 +120,9 @@ paths: type: integer get: summary: Show a bundle. + description: | + Retrieve a bundle by its ID. + The bundle must be either be public or be owned by the currently authenticated user. operationId: bundles_read responses: '200': @@ -131,6 +141,9 @@ paths: - bundles patch: summary: Update a bundle (partial). + description: + Partially update an existing bundle. + The bundle must be owned by the currently authenticated user. operationId: bundles_partial_update security: - basicAuth: [] @@ -205,6 +218,8 @@ paths: /api/covers: get: summary: List cover letters. + description: | + List all cover letters. operationId: covers_list parameters: - $ref: '#/components/parameters/Page' @@ -266,6 +281,8 @@ paths: type: integer get: summary: Show a cover letter. + description: | + Retrieve a cover letter by its ID. operationId: covers_read responses: '200': @@ -294,6 +311,8 @@ paths: type: integer get: summary: List cover letter comments + description: | + List all comments for the given cover letter. operationId: cover_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -338,6 +357,8 @@ paths: type: integer get: summary: Show a cover letter comment. + description: | + Retrieve a cover letter comment by its ID. operationId: cover_comments_read responses: '200': @@ -356,6 +377,9 @@ paths: - comments patch: summary: Update a cover letter comment (partial). + description: + Partially update an existing cover letter comment. + You must be a maintainer of the project that the cover letter comment belongs to. operationId: cover_comments_partial_update requestBody: $ref: '#/components/requestBodies/Comment' @@ -389,6 +413,9 @@ paths: /api/events: get: summary: List events. + description: | + List all events. + This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s). operationId: events_list parameters: - $ref: '#/components/parameters/Page' @@ -485,6 +512,8 @@ paths: /api/patches: get: summary: List patches. + description: | + List all patches. operationId: patches_list parameters: - $ref: '#/components/parameters/Page' @@ -574,6 +603,8 @@ paths: type: integer get: summary: Show a patch. + description: | + Retrieve a patch by its ID. operationId: patches_read responses: '200': @@ -592,6 +623,9 @@ paths: - patches patch: summary: Update a patch (partial). + description: + Partially update an existing patch. + You must be a maintainer of the project that the patch belongs to. operationId: patches_partial_update security: - basicAuth: [] @@ -682,7 +716,9 @@ paths: title: ID type: integer get: - summary: List comments + summary: List patch comments + description: | + List all comments for the given patch. operationId: patch_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -727,6 +763,8 @@ paths: type: integer get: summary: Show a patch comment. + description: | + Retrieve a patch comment by its ID and the ID of the patch. operationId: patch_comments_read responses: '200': @@ -745,6 +783,9 @@ paths: - comments patch: summary: Update a patch comment (partial). + description: + Partially update an existing patch comment. + You must be a maintainer of the project that the patch comment belongs to. operationId: patch_comments_partial_update requestBody: $ref: '#/components/requestBodies/Comment' @@ -786,6 +827,8 @@ paths: type: integer get: summary: List checks. + description: | + List all checks for the given patch. operationId: checks_list parameters: - $ref: '#/components/parameters/Page' @@ -890,6 +933,8 @@ paths: type: integer get: summary: Show a check. + description: | + Retrieve a check by its ID. operationId: checks_read responses: '200': @@ -909,6 +954,9 @@ paths: /api/people: get: summary: List people. + description: | + List all people. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_list security: - basicAuth: [] @@ -949,6 +997,9 @@ paths: type: integer get: summary: Show a person. + description: | + Retrieve a person by their ID. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_read security: - basicAuth: [] @@ -977,6 +1028,8 @@ paths: /api/projects: get: summary: List projects. + description: | + List all projects. operationId: projects_list parameters: - $ref: '#/components/parameters/Page' @@ -1009,6 +1062,8 @@ paths: type: string get: summary: Show a project. + description: | + Retrieve a project by its ID. operationId: projects_read responses: '200': @@ -1027,6 +1082,9 @@ paths: - projects patch: summary: Update a project (partial). + description: + Partially update an existing project. + You must be a maintainer of the project. operationId: projects_partial_update security: - basicAuth: [] @@ -1098,6 +1156,9 @@ paths: /api/series: get: summary: List series. + description: | + List all series. + A series is a collection of patches with an optional cover letter. operationId: series_list parameters: - $ref: '#/components/parameters/Page' @@ -1143,6 +1204,9 @@ paths: type: integer get: summary: Show a series. + description: | + Retrieve a series by its ID. + A series is a collection of patches with an optional cover letter. operationId: series_read responses: '200': @@ -1162,6 +1226,8 @@ paths: /api/users: get: summary: List users. + description: | + List all users. operationId: users_list security: - basicAuth: [] @@ -1202,6 +1268,8 @@ paths: type: integer get: summary: Show a user. + description: | + Retrieve a user by their ID. operationId: users_read security: - basicAuth: [] @@ -1229,6 +1297,9 @@ paths: - users patch: summary: Update a user (partial). + description: + Partially update a user account. + Only super users are allowed to update other user's accounts. operationId: users_partial_update security: - basicAuth: [] diff --git a/docs/api/schemas/patchwork.j2 b/docs/api/schemas/patchwork.j2 index 541e4f8a..516fbe88 100644 --- a/docs/api/schemas/patchwork.j2 +++ b/docs/api/schemas/patchwork.j2 @@ -23,6 +23,8 @@ paths: {% endif %} get: summary: List API resources. + description: | + Show paths to all supported API resources. operationId: api_list parameters: [] responses: @@ -37,6 +39,9 @@ paths: /api/{{ version_url}}bundles: get: summary: List bundles. + description: | + List all bundles that the current user has access to. + For unauthenticated requests, only public bundles can be shown. operationId: bundles_list parameters: - $ref: '#/components/parameters/Page' @@ -81,6 +86,8 @@ paths: {% if version >= (1, 2) %} post: summary: Create a bundle. + description: | + Create a new bundle. operationId: bundles_create security: - basicAuth: [] @@ -120,6 +127,9 @@ paths: type: integer get: summary: Show a bundle. + description: | + Retrieve a bundle by its ID. + The bundle must be either be public or be owned by the currently authenticated user. operationId: bundles_read responses: '200': @@ -139,6 +149,9 @@ paths: {% if version >= (1, 2) %} patch: summary: Update a bundle (partial). + description: + Partially update an existing bundle. + The bundle must be owned by the currently authenticated user. operationId: bundles_partial_update security: - basicAuth: [] @@ -214,6 +227,8 @@ paths: /api/{{ version_url }}covers: get: summary: List cover letters. + description: | + List all cover letters. operationId: covers_list parameters: - $ref: '#/components/parameters/Page' @@ -277,6 +292,8 @@ paths: type: integer get: summary: Show a cover letter. + description: | + Retrieve a cover letter by its ID. operationId: covers_read responses: '200': @@ -305,6 +322,8 @@ paths: type: integer get: summary: List cover letter comments + description: | + List all comments for the given cover letter. operationId: cover_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -350,6 +369,8 @@ paths: type: integer get: summary: Show a cover letter comment. + description: | + Retrieve a cover letter comment by its ID. operationId: cover_comments_read responses: '200': @@ -368,6 +389,9 @@ paths: - comments patch: summary: Update a cover letter comment (partial). + description: + Partially update an existing cover letter comment. + You must be a maintainer of the project that the cover letter comment belongs to. operationId: cover_comments_partial_update requestBody: $ref: '#/components/requestBodies/Comment' @@ -402,6 +426,9 @@ paths: /api/{{ version_url }}events: get: summary: List events. + description: | + List all events. + This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s). operationId: events_list parameters: - $ref: '#/components/parameters/Page' @@ -502,6 +529,8 @@ paths: /api/{{ version_url }}patches: get: summary: List patches. + description: | + List all patches. operationId: patches_list parameters: - $ref: '#/components/parameters/Page' @@ -593,6 +622,8 @@ paths: type: integer get: summary: Show a patch. + description: | + Retrieve a patch by its ID. operationId: patches_read responses: '200': @@ -611,6 +642,9 @@ paths: - patches patch: summary: Update a patch (partial). + description: + Partially update an existing patch. + You must be a maintainer of the project that the patch belongs to. operationId: patches_partial_update security: - basicAuth: [] @@ -705,7 +739,9 @@ paths: title: ID type: integer get: - summary: List comments + summary: List patch comments + description: | + List all comments for the given patch. operationId: patch_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -751,6 +787,8 @@ paths: type: integer get: summary: Show a patch comment. + description: | + Retrieve a patch comment by its ID and the ID of the patch. operationId: patch_comments_read responses: '200': @@ -769,6 +807,9 @@ paths: - comments patch: summary: Update a patch comment (partial). + description: + Partially update an existing patch comment. + You must be a maintainer of the project that the patch comment belongs to. operationId: patch_comments_partial_update requestBody: $ref: '#/components/requestBodies/Comment' @@ -811,6 +852,8 @@ paths: type: integer get: summary: List checks. + description: | + List all checks for the given patch. operationId: checks_list parameters: - $ref: '#/components/parameters/Page' @@ -915,6 +958,8 @@ paths: type: integer get: summary: Show a check. + description: | + Retrieve a check by its ID. operationId: checks_read responses: '200': @@ -934,6 +979,9 @@ paths: /api/{{ version_url }}people: get: summary: List people. + description: | + List all people. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_list security: - basicAuth: [] @@ -974,6 +1022,9 @@ paths: type: integer get: summary: Show a person. + description: | + Retrieve a person by their ID. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_read security: - basicAuth: [] @@ -1002,6 +1053,8 @@ paths: /api/{{ version_url }}projects: get: summary: List projects. + description: | + List all projects. operationId: projects_list parameters: - $ref: '#/components/parameters/Page' @@ -1034,6 +1087,8 @@ paths: type: string get: summary: Show a project. + description: | + Retrieve a project by its ID. operationId: projects_read responses: '200': @@ -1052,6 +1107,9 @@ paths: - projects patch: summary: Update a project (partial). + description: + Partially update an existing project. + You must be a maintainer of the project. operationId: projects_partial_update security: - basicAuth: [] @@ -1123,6 +1181,9 @@ paths: /api/{{ version_url }}series: get: summary: List series. + description: | + List all series. + A series is a collection of patches with an optional cover letter. operationId: series_list parameters: - $ref: '#/components/parameters/Page' @@ -1168,6 +1229,9 @@ paths: type: integer get: summary: Show a series. + description: | + Retrieve a series by its ID. + A series is a collection of patches with an optional cover letter. operationId: series_read responses: '200': @@ -1187,6 +1251,8 @@ paths: /api/{{ version_url }}users: get: summary: List users. + description: | + List all users. operationId: users_list security: - basicAuth: [] @@ -1227,6 +1293,8 @@ paths: type: integer get: summary: Show a user. + description: | + Retrieve a user by their ID. operationId: users_read security: - basicAuth: [] @@ -1258,6 +1326,9 @@ paths: - users patch: summary: Update a user (partial). + description: + Partially update a user account. + Only super users are allowed to update other user's accounts. operationId: users_partial_update security: - basicAuth: [] diff --git a/docs/api/schemas/v1.0/patchwork.yaml b/docs/api/schemas/v1.0/patchwork.yaml index 8c585975..d317f53f 100644 --- a/docs/api/schemas/v1.0/patchwork.yaml +++ b/docs/api/schemas/v1.0/patchwork.yaml @@ -18,6 +18,8 @@ paths: /api/1.0/: get: summary: List API resources. + description: | + Show paths to all supported API resources. operationId: api_list parameters: [] responses: @@ -32,6 +34,9 @@ paths: /api/1.0/bundles: get: summary: List bundles. + description: | + List all bundles that the current user has access to. + For unauthenticated requests, only public bundles can be shown. operationId: bundles_list parameters: - $ref: '#/components/parameters/Page' @@ -84,6 +89,9 @@ paths: type: integer get: summary: Show a bundle. + description: | + Retrieve a bundle by its ID. + The bundle must be either be public or be owned by the currently authenticated user. operationId: bundles_read responses: '200': @@ -103,6 +111,8 @@ paths: /api/1.0/covers: get: summary: List cover letters. + description: | + List all cover letters. operationId: covers_list parameters: - $ref: '#/components/parameters/Page' @@ -156,6 +166,8 @@ paths: type: integer get: summary: Show a cover letter. + description: | + Retrieve a cover letter by its ID. operationId: covers_read responses: '200': @@ -184,6 +196,8 @@ paths: type: integer get: summary: List cover letter comments + description: | + List all comments for the given cover letter. operationId: cover_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -213,6 +227,9 @@ paths: /api/1.0/events: get: summary: List events. + description: | + List all events. + This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s). operationId: events_list parameters: - $ref: '#/components/parameters/Page' @@ -306,6 +323,8 @@ paths: /api/1.0/patches: get: summary: List patches. + description: | + List all patches. operationId: patches_list parameters: - $ref: '#/components/parameters/Page' @@ -380,6 +399,8 @@ paths: type: integer get: summary: Show a patch. + description: | + Retrieve a patch by its ID. operationId: patches_read responses: '200': @@ -398,6 +419,9 @@ paths: - patches patch: summary: Update a patch (partial). + description: + Partially update an existing patch. + You must be a maintainer of the project that the patch belongs to. operationId: patches_partial_update security: - basicAuth: [] @@ -476,7 +500,9 @@ paths: title: ID type: integer get: - summary: List comments + summary: List patch comments + description: | + List all comments for the given patch. operationId: patch_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -514,6 +540,8 @@ paths: type: integer get: summary: List checks. + description: | + List all checks for the given patch. operationId: checks_list parameters: - $ref: '#/components/parameters/Page' @@ -618,6 +646,8 @@ paths: type: integer get: summary: Show a check. + description: | + Retrieve a check by its ID. operationId: checks_read responses: '200': @@ -637,6 +667,9 @@ paths: /api/1.0/people: get: summary: List people. + description: | + List all people. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_list security: - basicAuth: [] @@ -677,6 +710,9 @@ paths: type: integer get: summary: Show a person. + description: | + Retrieve a person by their ID. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_read security: - basicAuth: [] @@ -705,6 +741,8 @@ paths: /api/1.0/projects: get: summary: List projects. + description: | + List all projects. operationId: projects_list parameters: - $ref: '#/components/parameters/Page' @@ -737,6 +775,8 @@ paths: type: string get: summary: Show a project. + description: | + Retrieve a project by its ID. operationId: projects_read responses: '200': @@ -755,6 +795,9 @@ paths: - projects patch: summary: Update a project (partial). + description: + Partially update an existing project. + You must be a maintainer of the project. operationId: projects_partial_update security: - basicAuth: [] @@ -826,6 +869,9 @@ paths: /api/1.0/series: get: summary: List series. + description: | + List all series. + A series is a collection of patches with an optional cover letter. operationId: series_list parameters: - $ref: '#/components/parameters/Page' @@ -871,6 +917,9 @@ paths: type: integer get: summary: Show a series. + description: | + Retrieve a series by its ID. + A series is a collection of patches with an optional cover letter. operationId: series_read responses: '200': @@ -890,6 +939,8 @@ paths: /api/1.0/users: get: summary: List users. + description: | + List all users. operationId: users_list security: - basicAuth: [] @@ -930,6 +981,8 @@ paths: type: integer get: summary: Show a user. + description: | + Retrieve a user by their ID. operationId: users_read security: - basicAuth: [] @@ -957,6 +1010,9 @@ paths: - users patch: summary: Update a user (partial). + description: + Partially update a user account. + Only super users are allowed to update other user's accounts. operationId: users_partial_update security: - basicAuth: [] diff --git a/docs/api/schemas/v1.1/patchwork.yaml b/docs/api/schemas/v1.1/patchwork.yaml index 44b7bf6e..ce17d2f2 100644 --- a/docs/api/schemas/v1.1/patchwork.yaml +++ b/docs/api/schemas/v1.1/patchwork.yaml @@ -18,6 +18,8 @@ paths: /api/1.1/: get: summary: List API resources. + description: | + Show paths to all supported API resources. operationId: api_list parameters: [] responses: @@ -32,6 +34,9 @@ paths: /api/1.1/bundles: get: summary: List bundles. + description: | + List all bundles that the current user has access to. + For unauthenticated requests, only public bundles can be shown. operationId: bundles_list parameters: - $ref: '#/components/parameters/Page' @@ -84,6 +89,9 @@ paths: type: integer get: summary: Show a bundle. + description: | + Retrieve a bundle by its ID. + The bundle must be either be public or be owned by the currently authenticated user. operationId: bundles_read responses: '200': @@ -103,6 +111,8 @@ paths: /api/1.1/covers: get: summary: List cover letters. + description: | + List all cover letters. operationId: covers_list parameters: - $ref: '#/components/parameters/Page' @@ -156,6 +166,8 @@ paths: type: integer get: summary: Show a cover letter. + description: | + Retrieve a cover letter by its ID. operationId: covers_read responses: '200': @@ -184,6 +196,8 @@ paths: type: integer get: summary: List cover letter comments + description: | + List all comments for the given cover letter. operationId: cover_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -213,6 +227,9 @@ paths: /api/1.1/events: get: summary: List events. + description: | + List all events. + This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s). operationId: events_list parameters: - $ref: '#/components/parameters/Page' @@ -306,6 +323,8 @@ paths: /api/1.1/patches: get: summary: List patches. + description: | + List all patches. operationId: patches_list parameters: - $ref: '#/components/parameters/Page' @@ -380,6 +399,8 @@ paths: type: integer get: summary: Show a patch. + description: | + Retrieve a patch by its ID. operationId: patches_read responses: '200': @@ -398,6 +419,9 @@ paths: - patches patch: summary: Update a patch (partial). + description: + Partially update an existing patch. + You must be a maintainer of the project that the patch belongs to. operationId: patches_partial_update security: - basicAuth: [] @@ -476,7 +500,9 @@ paths: title: ID type: integer get: - summary: List comments + summary: List patch comments + description: | + List all comments for the given patch. operationId: patch_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -514,6 +540,8 @@ paths: type: integer get: summary: List checks. + description: | + List all checks for the given patch. operationId: checks_list parameters: - $ref: '#/components/parameters/Page' @@ -618,6 +646,8 @@ paths: type: integer get: summary: Show a check. + description: | + Retrieve a check by its ID. operationId: checks_read responses: '200': @@ -637,6 +667,9 @@ paths: /api/1.1/people: get: summary: List people. + description: | + List all people. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_list security: - basicAuth: [] @@ -677,6 +710,9 @@ paths: type: integer get: summary: Show a person. + description: | + Retrieve a person by their ID. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_read security: - basicAuth: [] @@ -705,6 +741,8 @@ paths: /api/1.1/projects: get: summary: List projects. + description: | + List all projects. operationId: projects_list parameters: - $ref: '#/components/parameters/Page' @@ -737,6 +775,8 @@ paths: type: string get: summary: Show a project. + description: | + Retrieve a project by its ID. operationId: projects_read responses: '200': @@ -755,6 +795,9 @@ paths: - projects patch: summary: Update a project (partial). + description: + Partially update an existing project. + You must be a maintainer of the project. operationId: projects_partial_update security: - basicAuth: [] @@ -826,6 +869,9 @@ paths: /api/1.1/series: get: summary: List series. + description: | + List all series. + A series is a collection of patches with an optional cover letter. operationId: series_list parameters: - $ref: '#/components/parameters/Page' @@ -871,6 +917,9 @@ paths: type: integer get: summary: Show a series. + description: | + Retrieve a series by its ID. + A series is a collection of patches with an optional cover letter. operationId: series_read responses: '200': @@ -890,6 +939,8 @@ paths: /api/1.1/users: get: summary: List users. + description: | + List all users. operationId: users_list security: - basicAuth: [] @@ -930,6 +981,8 @@ paths: type: integer get: summary: Show a user. + description: | + Retrieve a user by their ID. operationId: users_read security: - basicAuth: [] @@ -957,6 +1010,9 @@ paths: - users patch: summary: Update a user (partial). + description: + Partially update a user account. + Only super users are allowed to update other user's accounts. operationId: users_partial_update security: - basicAuth: [] diff --git a/docs/api/schemas/v1.2/patchwork.yaml b/docs/api/schemas/v1.2/patchwork.yaml index dcab86b4..dddaafe5 100644 --- a/docs/api/schemas/v1.2/patchwork.yaml +++ b/docs/api/schemas/v1.2/patchwork.yaml @@ -18,6 +18,8 @@ paths: /api/1.2/: get: summary: List API resources. + description: | + Show paths to all supported API resources. operationId: api_list parameters: [] responses: @@ -32,6 +34,9 @@ paths: /api/1.2/bundles: get: summary: List bundles. + description: | + List all bundles that the current user has access to. + For unauthenticated requests, only public bundles can be shown. operationId: bundles_list parameters: - $ref: '#/components/parameters/Page' @@ -75,6 +80,8 @@ paths: - bundles post: summary: Create a bundle. + description: | + Create a new bundle. operationId: bundles_create security: - basicAuth: [] @@ -113,6 +120,9 @@ paths: type: integer get: summary: Show a bundle. + description: | + Retrieve a bundle by its ID. + The bundle must be either be public or be owned by the currently authenticated user. operationId: bundles_read responses: '200': @@ -131,6 +141,9 @@ paths: - bundles patch: summary: Update a bundle (partial). + description: + Partially update an existing bundle. + The bundle must be owned by the currently authenticated user. operationId: bundles_partial_update security: - basicAuth: [] @@ -205,6 +218,8 @@ paths: /api/1.2/covers: get: summary: List cover letters. + description: | + List all cover letters. operationId: covers_list parameters: - $ref: '#/components/parameters/Page' @@ -266,6 +281,8 @@ paths: type: integer get: summary: Show a cover letter. + description: | + Retrieve a cover letter by its ID. operationId: covers_read responses: '200': @@ -294,6 +311,8 @@ paths: type: integer get: summary: List cover letter comments + description: | + List all comments for the given cover letter. operationId: cover_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -323,6 +342,9 @@ paths: /api/1.2/events: get: summary: List events. + description: | + List all events. + This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s). operationId: events_list parameters: - $ref: '#/components/parameters/Page' @@ -417,6 +439,8 @@ paths: /api/1.2/patches: get: summary: List patches. + description: | + List all patches. operationId: patches_list parameters: - $ref: '#/components/parameters/Page' @@ -506,6 +530,8 @@ paths: type: integer get: summary: Show a patch. + description: | + Retrieve a patch by its ID. operationId: patches_read responses: '200': @@ -524,6 +550,9 @@ paths: - patches patch: summary: Update a patch (partial). + description: + Partially update an existing patch. + You must be a maintainer of the project that the patch belongs to. operationId: patches_partial_update security: - basicAuth: [] @@ -614,7 +643,9 @@ paths: title: ID type: integer get: - summary: List comments + summary: List patch comments + description: | + List all comments for the given patch. operationId: patch_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -652,6 +683,8 @@ paths: type: integer get: summary: List checks. + description: | + List all checks for the given patch. operationId: checks_list parameters: - $ref: '#/components/parameters/Page' @@ -756,6 +789,8 @@ paths: type: integer get: summary: Show a check. + description: | + Retrieve a check by its ID. operationId: checks_read responses: '200': @@ -775,6 +810,9 @@ paths: /api/1.2/people: get: summary: List people. + description: | + List all people. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_list security: - basicAuth: [] @@ -815,6 +853,9 @@ paths: type: integer get: summary: Show a person. + description: | + Retrieve a person by their ID. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_read security: - basicAuth: [] @@ -843,6 +884,8 @@ paths: /api/1.2/projects: get: summary: List projects. + description: | + List all projects. operationId: projects_list parameters: - $ref: '#/components/parameters/Page' @@ -875,6 +918,8 @@ paths: type: string get: summary: Show a project. + description: | + Retrieve a project by its ID. operationId: projects_read responses: '200': @@ -893,6 +938,9 @@ paths: - projects patch: summary: Update a project (partial). + description: + Partially update an existing project. + You must be a maintainer of the project. operationId: projects_partial_update security: - basicAuth: [] @@ -964,6 +1012,9 @@ paths: /api/1.2/series: get: summary: List series. + description: | + List all series. + A series is a collection of patches with an optional cover letter. operationId: series_list parameters: - $ref: '#/components/parameters/Page' @@ -1009,6 +1060,9 @@ paths: type: integer get: summary: Show a series. + description: | + Retrieve a series by its ID. + A series is a collection of patches with an optional cover letter. operationId: series_read responses: '200': @@ -1028,6 +1082,8 @@ paths: /api/1.2/users: get: summary: List users. + description: | + List all users. operationId: users_list security: - basicAuth: [] @@ -1068,6 +1124,8 @@ paths: type: integer get: summary: Show a user. + description: | + Retrieve a user by their ID. operationId: users_read security: - basicAuth: [] @@ -1095,6 +1153,9 @@ paths: - users patch: summary: Update a user (partial). + description: + Partially update a user account. + Only super users are allowed to update other user's accounts. operationId: users_partial_update security: - basicAuth: [] diff --git a/docs/api/schemas/v1.3/patchwork.yaml b/docs/api/schemas/v1.3/patchwork.yaml index ea0f8cca..41b44832 100644 --- a/docs/api/schemas/v1.3/patchwork.yaml +++ b/docs/api/schemas/v1.3/patchwork.yaml @@ -18,6 +18,8 @@ paths: /api/1.3/: get: summary: List API resources. + description: | + Show paths to all supported API resources. operationId: api_list parameters: [] responses: @@ -32,6 +34,9 @@ paths: /api/1.3/bundles: get: summary: List bundles. + description: | + List all bundles that the current user has access to. + For unauthenticated requests, only public bundles can be shown. operationId: bundles_list parameters: - $ref: '#/components/parameters/Page' @@ -75,6 +80,8 @@ paths: - bundles post: summary: Create a bundle. + description: | + Create a new bundle. operationId: bundles_create security: - basicAuth: [] @@ -113,6 +120,9 @@ paths: type: integer get: summary: Show a bundle. + description: | + Retrieve a bundle by its ID. + The bundle must be either be public or be owned by the currently authenticated user. operationId: bundles_read responses: '200': @@ -131,6 +141,9 @@ paths: - bundles patch: summary: Update a bundle (partial). + description: + Partially update an existing bundle. + The bundle must be owned by the currently authenticated user. operationId: bundles_partial_update security: - basicAuth: [] @@ -205,6 +218,8 @@ paths: /api/1.3/covers: get: summary: List cover letters. + description: | + List all cover letters. operationId: covers_list parameters: - $ref: '#/components/parameters/Page' @@ -266,6 +281,8 @@ paths: type: integer get: summary: Show a cover letter. + description: | + Retrieve a cover letter by its ID. operationId: covers_read responses: '200': @@ -294,6 +311,8 @@ paths: type: integer get: summary: List cover letter comments + description: | + List all comments for the given cover letter. operationId: cover_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -338,6 +357,8 @@ paths: type: integer get: summary: Show a cover letter comment. + description: | + Retrieve a cover letter comment by its ID. operationId: cover_comments_read responses: '200': @@ -356,6 +377,9 @@ paths: - comments patch: summary: Update a cover letter comment (partial). + description: + Partially update an existing cover letter comment. + You must be a maintainer of the project that the cover letter comment belongs to. operationId: cover_comments_partial_update requestBody: $ref: '#/components/requestBodies/Comment' @@ -389,6 +413,9 @@ paths: /api/1.3/events: get: summary: List events. + description: | + List all events. + This list can be quite large. You are encouraged to use filters to narrow it to specific categories or project(s). operationId: events_list parameters: - $ref: '#/components/parameters/Page' @@ -485,6 +512,8 @@ paths: /api/1.3/patches: get: summary: List patches. + description: | + List all patches. operationId: patches_list parameters: - $ref: '#/components/parameters/Page' @@ -574,6 +603,8 @@ paths: type: integer get: summary: Show a patch. + description: | + Retrieve a patch by its ID. operationId: patches_read responses: '200': @@ -592,6 +623,9 @@ paths: - patches patch: summary: Update a patch (partial). + description: + Partially update an existing patch. + You must be a maintainer of the project that the patch belongs to. operationId: patches_partial_update security: - basicAuth: [] @@ -682,7 +716,9 @@ paths: title: ID type: integer get: - summary: List comments + summary: List patch comments + description: | + List all comments for the given patch. operationId: patch_comments_list parameters: - $ref: '#/components/parameters/Page' @@ -727,6 +763,8 @@ paths: type: integer get: summary: Show a patch comment. + description: | + Retrieve a patch comment by its ID and the ID of the patch. operationId: patch_comments_read responses: '200': @@ -745,6 +783,9 @@ paths: - comments patch: summary: Update a patch comment (partial). + description: + Partially update an existing patch comment. + You must be a maintainer of the project that the patch comment belongs to. operationId: patch_comments_partial_update requestBody: $ref: '#/components/requestBodies/Comment' @@ -786,6 +827,8 @@ paths: type: integer get: summary: List checks. + description: | + List all checks for the given patch. operationId: checks_list parameters: - $ref: '#/components/parameters/Page' @@ -890,6 +933,8 @@ paths: type: integer get: summary: Show a check. + description: | + Retrieve a check by its ID. operationId: checks_read responses: '200': @@ -909,6 +954,9 @@ paths: /api/1.3/people: get: summary: List people. + description: | + List all people. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_list security: - basicAuth: [] @@ -949,6 +997,9 @@ paths: type: integer get: summary: Show a person. + description: | + Retrieve a person by their ID. + A person is anyone that has submitted a patch, a series of patches, or a comment to any project. operationId: people_read security: - basicAuth: [] @@ -977,6 +1028,8 @@ paths: /api/1.3/projects: get: summary: List projects. + description: | + List all projects. operationId: projects_list parameters: - $ref: '#/components/parameters/Page' @@ -1009,6 +1062,8 @@ paths: type: string get: summary: Show a project. + description: | + Retrieve a project by its ID. operationId: projects_read responses: '200': @@ -1027,6 +1082,9 @@ paths: - projects patch: summary: Update a project (partial). + description: + Partially update an existing project. + You must be a maintainer of the project. operationId: projects_partial_update security: - basicAuth: [] @@ -1098,6 +1156,9 @@ paths: /api/1.3/series: get: summary: List series. + description: | + List all series. + A series is a collection of patches with an optional cover letter. operationId: series_list parameters: - $ref: '#/components/parameters/Page' @@ -1143,6 +1204,9 @@ paths: type: integer get: summary: Show a series. + description: | + Retrieve a series by its ID. + A series is a collection of patches with an optional cover letter. operationId: series_read responses: '200': @@ -1162,6 +1226,8 @@ paths: /api/1.3/users: get: summary: List users. + description: | + List all users. operationId: users_list security: - basicAuth: [] @@ -1202,6 +1268,8 @@ paths: type: integer get: summary: Show a user. + description: | + Retrieve a user by their ID. operationId: users_read security: - basicAuth: [] @@ -1229,6 +1297,9 @@ paths: - users patch: summary: Update a user (partial). + description: + Partially update a user account. + Only super users are allowed to update other user's accounts. operationId: users_partial_update security: - basicAuth: []