From 908e8942ccae5b7966c7084780b3441e2190d9c1 Mon Sep 17 00:00:00 2001 From: Antoine GIRARD Date: Tue, 12 Jun 2018 16:59:22 +0200 Subject: Fix swagger errors (#4220) Fix all the resting errors to have a valid swagger file. They are still some warnings but nothing blocking. Doing so I found that some request still misses son parameters for some POST/PUT/PATCH request. This means the a client generated from the swagger file will not work completely. Fix #4088 by activating validation in drone Should fix #4010. --- routers/api/v1/misc/markdown.go | 9 ++++-- routers/api/v1/org/hook.go | 49 +++++++++++++++++++++++++++++ routers/api/v1/org/team.go | 6 ++-- routers/api/v1/repo/file.go | 2 +- routers/api/v1/repo/hook.go | 7 ++++- routers/api/v1/repo/issue_comment.go | 4 +-- routers/api/v1/repo/issue_tracked_time.go | 8 ++--- routers/api/v1/repo/milestone.go | 43 ++++++++++++++----------- routers/api/v1/repo/repo.go | 12 +++---- routers/api/v1/swagger/options.go | 52 +++++++++++++++++++++++++------ routers/api/v1/swagger/repo.go | 1 + routers/api/v1/user/app.go | 12 +++++++ routers/api/v1/user/follower.go | 4 +-- 13 files changed, 158 insertions(+), 51 deletions(-) (limited to 'routers/api') diff --git a/routers/api/v1/misc/markdown.go b/routers/api/v1/misc/markdown.go index fd7d1489b3..633dff98eb 100644 --- a/routers/api/v1/misc/markdown.go +++ b/routers/api/v1/misc/markdown.go @@ -62,9 +62,12 @@ func MarkdownRaw(ctx *context.APIContext) { // --- // summary: Render raw markdown as HTML // parameters: - // - name: body - // in: body - // type: string + // - name: body + // in: body + // description: Request body to render + // required: true + // schema: + // type: string // consumes: // - text/plain // produces: diff --git a/routers/api/v1/org/hook.go b/routers/api/v1/org/hook.go index 0a77d795e6..83d2a5e5ba 100644 --- a/routers/api/v1/org/hook.go +++ b/routers/api/v1/org/hook.go @@ -20,6 +20,12 @@ func ListHooks(ctx *context.APIContext) { // summary: List an organization's webhooks // produces: // - application/json + // parameters: + // - name: org + // in: path + // description: name of the organization + // type: string + // required: true // responses: // "200": // "$ref": "#/responses/HookList" @@ -43,6 +49,17 @@ func GetHook(ctx *context.APIContext) { // summary: Get a hook // produces: // - application/json + // parameters: + // - name: org + // in: path + // description: name of the organization + // type: string + // required: true + // - name: id + // in: path + // description: id of the hook to get + // type: integer + // required: true // responses: // "200": // "$ref": "#/responses/Hook" @@ -64,9 +81,17 @@ func CreateHook(ctx *context.APIContext, form api.CreateHookOption) { // - application/json // produces: // - application/json + // parameters: + // - name: org + // in: path + // description: name of the organization + // type: string + // required: true // responses: // "201": // "$ref": "#/responses/Hook" + + //TODO in body params if !utils.CheckCreateHookOption(ctx, &form) { return } @@ -82,9 +107,22 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) { // - application/json // produces: // - application/json + // parameters: + // - name: org + // in: path + // description: name of the organization + // type: string + // required: true + // - name: id + // in: path + // description: id of the hook to update + // type: integer + // required: true // responses: // "200": // "$ref": "#/responses/Hook" + + //TODO in body params hookID := ctx.ParamsInt64(":id") utils.EditOrgHook(ctx, &form, hookID) } @@ -96,6 +134,17 @@ func DeleteHook(ctx *context.APIContext) { // summary: Delete a hook // produces: // - application/json + // parameters: + // - name: org + // in: path + // description: name of the organization + // type: string + // required: true + // - name: id + // in: path + // description: id of the hook to delete + // type: integer + // required: true // responses: // "204": // "$ref": "#/responses/empty" diff --git a/routers/api/v1/org/team.go b/routers/api/v1/org/team.go index 408d8921db..b8dd026bf3 100644 --- a/routers/api/v1/org/team.go +++ b/routers/api/v1/org/team.go @@ -227,7 +227,7 @@ func AddTeamMember(ctx *context.APIContext) { // RemoveTeamMember api for remove one member from a team func RemoveTeamMember(ctx *context.APIContext) { - // swagger:operation DELETE /teams/{id}/members/{username} organization orgAddTeamMember + // swagger:operation DELETE /teams/{id}/members/{username} organization orgRemoveTeamMember // --- // summary: Remove a team member // produces: @@ -306,7 +306,7 @@ func getRepositoryByParams(ctx *context.APIContext) *models.Repository { // AddTeamRepository api for adding a repository to a team func AddTeamRepository(ctx *context.APIContext) { - // swagger:operation PUT /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember + // swagger:operation PUT /teams/{id}/repos/{org}/{repo} organization orgAddTeamRepository // --- // summary: Add a repository to a team // produces: @@ -350,7 +350,7 @@ func AddTeamRepository(ctx *context.APIContext) { // RemoveTeamRepository api for removing a repository from a team func RemoveTeamRepository(ctx *context.APIContext) { - // swagger:operation DELETE /teams/{id}/repos/{org}/{repo} organization orgAddTeamMember + // swagger:operation DELETE /teams/{id}/repos/{org}/{repo} organization orgRemoveTeamRepository // --- // summary: Remove a repository from a team // description: This does not delete the repository, it only removes the diff --git a/routers/api/v1/repo/file.go b/routers/api/v1/repo/file.go index a3c8309ac5..610247bc27 100644 --- a/routers/api/v1/repo/file.go +++ b/routers/api/v1/repo/file.go @@ -64,7 +64,7 @@ func GetRawFile(ctx *context.APIContext) { // GetArchive get archive of a repository func GetArchive(ctx *context.APIContext) { - // swagger:operation GET /repos/{owner}/{repo}/archive/{filepath} repository repoGetArchive + // swagger:operation GET /repos/{owner}/{repo}/archive/{archive} repository repoGetArchive // --- // summary: Get an archive of a repository // produces: diff --git a/routers/api/v1/repo/hook.go b/routers/api/v1/repo/hook.go index e412a7f1f2..1f121dfc38 100644 --- a/routers/api/v1/repo/hook.go +++ b/routers/api/v1/repo/hook.go @@ -189,6 +189,11 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) { // description: name of the repo // type: string // required: true + // - name: id + // in: path + // description: index of the hook + // type: integer + // required: true // - name: body // in: body // schema: @@ -202,7 +207,7 @@ func EditHook(ctx *context.APIContext, form api.EditHookOption) { // DeleteHook delete a hook of a repository func DeleteHook(ctx *context.APIContext) { - // swagger:operation DELETE /repos/{user}/{repo}/hooks/{id} repository repoDeleteHook + // swagger:operation DELETE /repos/{owner}/{repo}/hooks/{id} repository repoDeleteHook // --- // summary: Delete a hook in a repository // produces: diff --git a/routers/api/v1/repo/issue_comment.go b/routers/api/v1/repo/issue_comment.go index 2865ea9165..0cbf6493d3 100644 --- a/routers/api/v1/repo/issue_comment.go +++ b/routers/api/v1/repo/issue_comment.go @@ -31,7 +31,7 @@ func ListIssueComments(ctx *context.APIContext) { // description: name of the repo // type: string // required: true - // - name: id + // - name: index // in: path // description: index of the issue // type: integer @@ -139,7 +139,7 @@ func CreateIssueComment(ctx *context.APIContext, form api.CreateIssueCommentOpti // description: name of the repo // type: string // required: true - // - name: id + // - name: index // in: path // description: index of the issue // type: integer diff --git a/routers/api/v1/repo/issue_tracked_time.go b/routers/api/v1/repo/issue_tracked_time.go index 1111d672a7..9be9fee91a 100644 --- a/routers/api/v1/repo/issue_tracked_time.go +++ b/routers/api/v1/repo/issue_tracked_time.go @@ -21,7 +21,7 @@ func trackedTimesToAPIFormat(trackedTimes []*models.TrackedTime) []*api.TrackedT // ListTrackedTimes list all the tracked times of an issue func ListTrackedTimes(ctx *context.APIContext) { - // swagger:operation GET /repos/{owner}/{repo}/issues/{index}/times issue issueTrackedTimes + // swagger:operation GET /repos/{owner}/{repo}/issues/{id}/times issue issueTrackedTimes // --- // summary: List an issue's tracked times // produces: @@ -37,7 +37,7 @@ func ListTrackedTimes(ctx *context.APIContext) { // description: name of the repo // type: string // required: true - // - name: repo + // - name: id // in: path // description: index of the issue // type: integer @@ -70,7 +70,7 @@ func ListTrackedTimes(ctx *context.APIContext) { // AddTime adds time manual to the given issue func AddTime(ctx *context.APIContext, form api.AddTimeOption) { - // swagger:operation Post /repos/{owner}/{repo}/issues/{index}/times issue issueAddTime + // swagger:operation Post /repos/{owner}/{repo}/issues/{id}/times issue issueAddTime // --- // summary: Add a tracked time to a issue // consumes: @@ -132,7 +132,7 @@ func AddTime(ctx *context.APIContext, form api.AddTimeOption) { // ListTrackedTimesByUser lists all tracked times of the user func ListTrackedTimesByUser(ctx *context.APIContext) { - // swagger:operation GET /repos/{owner}/{repo}/times/{tracker} user userTrackedTimes + // swagger:operation GET /repos/{owner}/{repo}/times/{user} user userTrackedTimes // --- // summary: List a user's tracked times in a repo // produces: diff --git a/routers/api/v1/repo/milestone.go b/routers/api/v1/repo/milestone.go index 3953b0c3c0..a138cb7a69 100644 --- a/routers/api/v1/repo/milestone.go +++ b/routers/api/v1/repo/milestone.go @@ -16,14 +16,25 @@ import ( // ListMilestones list all the milestones for a repository func ListMilestones(ctx *context.APIContext) { - // swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone + // swagger:operation GET /repos/{owner}/{repo}/milestones issue issueGetMilestonesList // --- - // summary: Get a milestone + // summary: Get all of a repository's milestones // produces: // - application/json + // parameters: + // - name: owner + // in: path + // description: owner of the repo + // type: string + // required: true + // - name: repo + // in: path + // description: name of the repo + // type: string + // required: true // responses: // "200": - // "$ref": "#/responses/Milestone" + // "$ref": "#/responses/MilestoneList" milestones, err := models.GetMilestonesByRepoID(ctx.Repo.Repository.ID) if err != nil { ctx.Error(500, "GetMilestonesByRepoID", err) @@ -39,9 +50,9 @@ func ListMilestones(ctx *context.APIContext) { // GetMilestone get a milestone for a repository func GetMilestone(ctx *context.APIContext) { - // swagger:operation GET /repos/{owner}/{repo}/milestones issue issueGetMilestones + // swagger:operation GET /repos/{owner}/{repo}/milestones/{id} issue issueGetMilestone // --- - // summary: Get all of a repository's milestones + // summary: Get a milestone // produces: // - application/json // parameters: @@ -55,25 +66,14 @@ func GetMilestone(ctx *context.APIContext) { // description: name of the repo // type: string // required: true - // parameters: - // - name: owner - // in: path - // description: owner of the repo - // type: string - // required: true - // - name: repo - // in: path - // description: name of the repo - // type: string - // required: true // - name: id // in: path - // description: id of the milestone to get + // description: id of the milestone // type: integer // required: true // responses: // "200": - // "$ref": "#/responses/MilestoneList" + // "$ref": "#/responses/Milestone" milestone, err := models.GetMilestoneByRepoID(ctx.Repo.Repository.ID, ctx.ParamsInt64(":id")) if err != nil { if models.IsErrMilestoneNotExist(err) { @@ -152,6 +152,11 @@ func EditMilestone(ctx *context.APIContext, form api.EditMilestoneOption) { // description: name of the repo // type: string // required: true + // - name: id + // in: path + // description: id of the milestone + // type: integer + // required: true // - name: body // in: body // schema: @@ -202,7 +207,7 @@ func DeleteMilestone(ctx *context.APIContext) { // description: name of the repo // type: string // required: true - // - name: body + // - name: id // in: path // description: id of the milestone to delete // type: integer diff --git a/routers/api/v1/repo/repo.go b/routers/api/v1/repo/repo.go index 9f64dda61d..ccfe0440c8 100644 --- a/routers/api/v1/repo/repo.go +++ b/routers/api/v1/repo/repo.go @@ -508,13 +508,13 @@ func TopicSearch(ctx *context.Context) { // --- // summary: search topics via keyword // produces: - // - application/json + // - application/json // parameters: - // - name: keyword - // in: path - // description: id of the repo to get - // type: integer - // required: true + // - name: q + // in: query + // description: keywords to search + // required: true + // type: string // responses: // "200": // "$ref": "#/responses/Repository" diff --git a/routers/api/v1/swagger/options.go b/routers/api/v1/swagger/options.go index 8d9363fe91..4f2461f465 100644 --- a/routers/api/v1/swagger/options.go +++ b/routers/api/v1/swagger/options.go @@ -15,55 +15,87 @@ import ( // parameterBodies // swagger:response parameterBodies type swaggerParameterBodies struct { + // in:body AddCollaboratorOption api.AddCollaboratorOption + // in:body CreateEmailOption api.CreateEmailOption + // in:body DeleteEmailOption api.DeleteEmailOption + // in:body CreateHookOption api.CreateHookOption - EditHookOption api.EditHookOption + // in:body + EditHookOption api.EditHookOption + // in:body CreateIssueOption api.CreateIssueOption - EditIssueOption api.EditIssueOption + // in:body + EditIssueOption api.EditIssueOption + // in:body CreateIssueCommentOption api.CreateIssueCommentOption - EditIssueCommentOption api.EditIssueCommentOption + // in:body + EditIssueCommentOption api.EditIssueCommentOption + // in:body IssueLabelsOption api.IssueLabelsOption + // in:body CreateKeyOption api.CreateKeyOption + // in:body CreateLabelOption api.CreateLabelOption - EditLabelOption api.EditLabelOption + // in:body + EditLabelOption api.EditLabelOption + // in:body MarkdownOption api.MarkdownOption + // in:body CreateMilestoneOption api.CreateMilestoneOption - EditMilestoneOption api.EditMilestoneOption + // in:body + EditMilestoneOption api.EditMilestoneOption + // in:body CreateOrgOption api.CreateOrgOption - EditOrgOption api.EditOrgOption + // in:body + EditOrgOption api.EditOrgOption + // in:body CreatePullRequestOption api.CreatePullRequestOption - EditPullRequestOption api.EditPullRequestOption + // in:body + EditPullRequestOption api.EditPullRequestOption + // in:body CreateReleaseOption api.CreateReleaseOption - EditReleaseOption api.EditReleaseOption + // in:body + EditReleaseOption api.EditReleaseOption + // in:body CreateRepoOption api.CreateRepoOption + // in:body CreateForkOption api.CreateForkOption + // in:body CreateStatusOption api.CreateStatusOption + // in:body CreateTeamOption api.CreateTeamOption - EditTeamOption api.EditTeamOption + // in:body + EditTeamOption api.EditTeamOption + // in:body AddTimeOption api.AddTimeOption + // in:body CreateUserOption api.CreateUserOption - EditUserOption api.EditUserOption + // in:body + EditUserOption api.EditUserOption + // in:body MigrateRepoForm auth.MigrateRepoForm + // in:body EditAttachmentOptions api.EditAttachmentOptions } diff --git a/routers/api/v1/swagger/repo.go b/routers/api/v1/swagger/repo.go index 97837dfc24..9decc8f588 100644 --- a/routers/api/v1/swagger/repo.go +++ b/routers/api/v1/swagger/repo.go @@ -102,6 +102,7 @@ type swaggerResponseWatchInfo struct { // SearchResults // swagger:response SearchResults type swaggerResponseSearchResults struct { + // in:body Body api.SearchResults `json:"body"` } diff --git a/routers/api/v1/user/app.go b/routers/api/v1/user/app.go index e1f75de683..fc4118649c 100644 --- a/routers/api/v1/user/app.go +++ b/routers/api/v1/user/app.go @@ -18,6 +18,12 @@ func ListAccessTokens(ctx *context.APIContext) { // summary: List the authenticated user's access tokens // produces: // - application/json + // parameters: + // - name: username + // in: path + // description: username of user + // type: string + // required: true // responses: // "200": // "$ref": "#/responses/AccessTokenList" @@ -46,6 +52,12 @@ func CreateAccessToken(ctx *context.APIContext, form api.CreateAccessTokenOption // - application/json // produces: // - application/json + // parameters: + // - name: username + // in: path + // description: username of user + // type: string + // required: true // responses: // "200": // "$ref": "#/responses/AccessToken" diff --git a/routers/api/v1/user/follower.go b/routers/api/v1/user/follower.go index 49d13cc380..284b7323c3 100644 --- a/routers/api/v1/user/follower.go +++ b/routers/api/v1/user/follower.go @@ -119,11 +119,11 @@ func checkUserFollowing(ctx *context.APIContext, u *models.User, followID int64) // CheckMyFollowing whether the given user is followed by the authenticated user func CheckMyFollowing(ctx *context.APIContext) { - // swagger:operation GET /user/following/{followee} user userCurrentCheckFollowing + // swagger:operation GET /user/following/{username} user userCurrentCheckFollowing // --- // summary: Check whether a user is followed by the authenticated user // parameters: - // - name: followee + // - name: username // in: path // description: username of followed user // type: string -- cgit v1.2.3