From d638067d3cb0a7f69b4d899f65b9be4940bd3e41 Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Sat, 19 Oct 2024 22:11:56 +0200 Subject: [PATCH] API: enhance SearchIssues swagger docs (#32208) this will result in better api clients generated out of the openapi docs ... for SearchIssues --- *Sponsored by Kithara Software GmbH* --- routers/api/v1/repo/issue.go | 51 +++++++++++++++++++----------- templates/swagger/v1_json.tmpl | 58 ++++++++++++++++++++++++---------- 2 files changed, 73 insertions(+), 36 deletions(-) diff --git a/routers/api/v1/repo/issue.go b/routers/api/v1/repo/issue.go index d8c39b0f69b..e86fb3ccb1c 100644 --- a/routers/api/v1/repo/issue.go +++ b/routers/api/v1/repo/issue.go @@ -41,80 +41,93 @@ func SearchIssues(ctx *context.APIContext) { // parameters: // - name: state // in: query - // description: whether issue is open or closed + // description: State of the issue // type: string + // enum: [open, closed, all] + // default: open // - name: labels // in: query - // description: comma separated list of labels. Fetch only issues that have any of this labels. Non existent labels are discarded + // description: Comma-separated list of label names. Fetch only issues that have any of these labels. Non existent labels are discarded. // type: string // - name: milestones // in: query - // description: comma separated list of milestone names. Fetch only issues that have any of this milestones. Non existent are discarded + // description: Comma-separated list of milestone names. Fetch only issues that have any of these milestones. Non existent milestones are discarded. // type: string // - name: q // in: query - // description: search string + // description: Search string // type: string // - name: priority_repo_id // in: query - // description: repository to prioritize in the results + // description: Repository ID to prioritize in the results // type: integer // format: int64 // - name: type // in: query - // description: filter by type (issues / pulls) if set + // description: Filter by issue type // type: string + // enum: [issues, pulls] // - name: since // in: query - // description: Only show notifications updated after the given time. This is a timestamp in RFC 3339 format + // description: Only show issues updated after the given time (RFC 3339 format) // type: string // format: date-time - // required: false // - name: before // in: query - // description: Only show notifications updated before the given time. This is a timestamp in RFC 3339 format + // description: Only show issues updated before the given time (RFC 3339 format) // type: string // format: date-time - // required: false // - name: assigned // in: query - // description: filter (issues / pulls) assigned to you, default is false + // description: Filter issues or pulls assigned to the authenticated user // type: boolean + // default: false // - name: created // in: query - // description: filter (issues / pulls) created by you, default is false + // description: Filter issues or pulls created by the authenticated user // type: boolean + // default: false // - name: mentioned // in: query - // description: filter (issues / pulls) mentioning you, default is false + // description: Filter issues or pulls mentioning the authenticated user // type: boolean + // default: false // - name: review_requested // in: query - // description: filter pulls requesting your review, default is false + // description: Filter pull requests where the authenticated user's review was requested // type: boolean + // default: false // - name: reviewed // in: query - // description: filter pulls reviewed by you, default is false + // description: Filter pull requests reviewed by the authenticated user // type: boolean + // default: false // - name: owner // in: query - // description: filter by owner + // description: Filter by repository owner // type: string // - name: team // in: query - // description: filter by team (requires organization owner parameter to be provided) + // description: Filter by team (requires organization owner parameter) // type: string // - name: page // in: query - // description: page number of results to return (1-based) + // description: Page number of results to return (1-based) // type: integer + // minimum: 1 + // default: 1 // - name: limit // in: query - // description: page size of results + // description: Number of items per page // type: integer + // minimum: 0 // responses: // "200": // "$ref": "#/responses/IssueList" + // "400": + // "$ref": "#/responses/error" + // "422": + // "$ref": "#/responses/validationError" before, since, err := context.GetQueryBeforeSince(ctx.Base) if err != nil { diff --git a/templates/swagger/v1_json.tmpl b/templates/swagger/v1_json.tmpl index 2cbd8782d84..a2b75bd8739 100644 --- a/templates/swagger/v1_json.tmpl +++ b/templates/swagger/v1_json.tmpl @@ -3444,107 +3444,125 @@ "operationId": "issueSearchIssues", "parameters": [ { + "enum": [ + "open", + "closed", + "all" + ], "type": "string", - "description": "whether issue is open or closed", + "default": "open", + "description": "State of the issue", "name": "state", "in": "query" }, { "type": "string", - "description": "comma separated list of labels. Fetch only issues that have any of this labels. Non existent labels are discarded", + "description": "Comma-separated list of label names. Fetch only issues that have any of these labels. Non existent labels are discarded.", "name": "labels", "in": "query" }, { "type": "string", - "description": "comma separated list of milestone names. Fetch only issues that have any of this milestones. Non existent are discarded", + "description": "Comma-separated list of milestone names. Fetch only issues that have any of these milestones. Non existent milestones are discarded.", "name": "milestones", "in": "query" }, { "type": "string", - "description": "search string", + "description": "Search string", "name": "q", "in": "query" }, { "type": "integer", "format": "int64", - "description": "repository to prioritize in the results", + "description": "Repository ID to prioritize in the results", "name": "priority_repo_id", "in": "query" }, { + "enum": [ + "issues", + "pulls" + ], "type": "string", - "description": "filter by type (issues / pulls) if set", + "description": "Filter by issue type", "name": "type", "in": "query" }, { "type": "string", "format": "date-time", - "description": "Only show notifications updated after the given time. This is a timestamp in RFC 3339 format", + "description": "Only show issues updated after the given time (RFC 3339 format)", "name": "since", "in": "query" }, { "type": "string", "format": "date-time", - "description": "Only show notifications updated before the given time. This is a timestamp in RFC 3339 format", + "description": "Only show issues updated before the given time (RFC 3339 format)", "name": "before", "in": "query" }, { "type": "boolean", - "description": "filter (issues / pulls) assigned to you, default is false", + "default": false, + "description": "Filter issues or pulls assigned to the authenticated user", "name": "assigned", "in": "query" }, { "type": "boolean", - "description": "filter (issues / pulls) created by you, default is false", + "default": false, + "description": "Filter issues or pulls created by the authenticated user", "name": "created", "in": "query" }, { "type": "boolean", - "description": "filter (issues / pulls) mentioning you, default is false", + "default": false, + "description": "Filter issues or pulls mentioning the authenticated user", "name": "mentioned", "in": "query" }, { "type": "boolean", - "description": "filter pulls requesting your review, default is false", + "default": false, + "description": "Filter pull requests where the authenticated user's review was requested", "name": "review_requested", "in": "query" }, { "type": "boolean", - "description": "filter pulls reviewed by you, default is false", + "default": false, + "description": "Filter pull requests reviewed by the authenticated user", "name": "reviewed", "in": "query" }, { "type": "string", - "description": "filter by owner", + "description": "Filter by repository owner", "name": "owner", "in": "query" }, { "type": "string", - "description": "filter by team (requires organization owner parameter to be provided)", + "description": "Filter by team (requires organization owner parameter)", "name": "team", "in": "query" }, { + "minimum": 1, "type": "integer", - "description": "page number of results to return (1-based)", + "default": 1, + "description": "Page number of results to return (1-based)", "name": "page", "in": "query" }, { + "minimum": 0, "type": "integer", - "description": "page size of results", + "description": "Number of items per page", "name": "limit", "in": "query" } @@ -3552,6 +3570,12 @@ "responses": { "200": { "$ref": "#/responses/IssueList" + }, + "400": { + "$ref": "#/responses/error" + }, + "422": { + "$ref": "#/responses/validationError" } } }