Update swagger documentation (#2899)

* Update swagger documentation

Add docs for missing endpoints
Add documentation for request parameters
Make parameter naming consistent
Fix response documentation

* Restore delete comments
This commit is contained in:
Ethan Koenig 2017-11-12 23:02:25 -08:00 committed by Lauris BH
parent 4287d100b3
commit f26f4a7e01
72 changed files with 8875 additions and 2323 deletions

View file

@ -15,6 +15,25 @@ import (
// ListLabels list all the labels of a repository
func ListLabels(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/labels issue issueListLabels
// ---
// summary: Get all of a repository's labels
// 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/LabelList"
labels, err := models.GetLabelsByRepoID(ctx.Repo.Repository.ID, ctx.Query("sort"))
if err != nil {
ctx.Error(500, "GetLabelsByRepoID", err)
@ -30,6 +49,30 @@ func ListLabels(ctx *context.APIContext) {
// GetLabel get label by repository and label id
func GetLabel(ctx *context.APIContext) {
// swagger:operation GET /repos/{owner}/{repo}/labels/{id} issue issueGetLabel
// ---
// summary: Get a single label
// 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
// - name: id
// in: path
// description: id of the label to get
// type: integer
// required: true
// responses:
// "200":
// "$ref": "#/responses/Label"
var (
label *models.Label
err error
@ -54,6 +97,31 @@ func GetLabel(ctx *context.APIContext) {
// CreateLabel create a label for a repository
func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
// swagger:operation POST /repos/{owner}/{repo}/labels issue issueCreateLabel
// ---
// summary: Create a label
// consumes:
// - application/json
// 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
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/CreateLabelOption"
// responses:
// "201":
// "$ref": "#/responses/Label"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -73,6 +141,36 @@ func CreateLabel(ctx *context.APIContext, form api.CreateLabelOption) {
// EditLabel modify a label for a repository
func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
// swagger:operation PATCH /repos/{owner}/{repo}/labels/{id} issue issueEditLabel
// ---
// summary: Update a label
// consumes:
// - application/json
// 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
// - name: id
// in: path
// description: id of the label to edit
// type: integer
// required: true
// - name: body
// in: body
// schema:
// "$ref": "#/definitions/EditLabelOption"
// responses:
// "200":
// "$ref": "#/responses/Label"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return
@ -103,6 +201,28 @@ func EditLabel(ctx *context.APIContext, form api.EditLabelOption) {
// DeleteLabel delete a label for a repository
func DeleteLabel(ctx *context.APIContext) {
// swagger:operation DELETE /repos/{owner}/{repo}/labels/{id} issue issueDeleteLabel
// ---
// summary: Delete a label
// 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 label to delete
// type: integer
// required: true
// responses:
// "204":
// "$ref": "#/responses/empty"
if !ctx.Repo.IsWriter() {
ctx.Status(403)
return