mirror of
https://codeberg.org/forgejo/forgejo.git
synced 2025-06-19 15:40:50 +00:00
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
Lauris BH
parent
4287d100b3
commit
f26f4a7e01
72 changed files with 8875 additions and 2323 deletions
|
|
@ -20,45 +20,40 @@ import (
|
|||
"code.gitea.io/gitea/routers/api/v1/convert"
|
||||
)
|
||||
|
||||
// SearchRepoOption options when searching repositories
|
||||
// swagger:parameters repoSearch
|
||||
type SearchRepoOption struct { // TODO: Move SearchRepoOption to Gitea SDK
|
||||
// Keyword to search
|
||||
//
|
||||
// in: query
|
||||
Keyword string `json:"q"`
|
||||
// Repository owner to search
|
||||
//
|
||||
// in: query
|
||||
OwnerID int64 `json:"uid"`
|
||||
// Limit of result
|
||||
//
|
||||
// maximum: setting.ExplorePagingNum
|
||||
// in: query
|
||||
PageSize int `json:"limit"`
|
||||
// Type of repository to search, related to owner
|
||||
//
|
||||
// in: query
|
||||
SearchMode string `json:"mode"`
|
||||
// Search only owners repositories
|
||||
// Has effect only if owner is provided and mode is not "collaborative"
|
||||
//
|
||||
// in: query
|
||||
OwnerExclusive bool `json:"exclusive"`
|
||||
}
|
||||
|
||||
// Search repositories via options
|
||||
func Search(ctx *context.APIContext) {
|
||||
// swagger:route GET /repos/search repository repoSearch
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 200: SearchResults
|
||||
// 422: validationError
|
||||
// 500: SearchError
|
||||
|
||||
// swagger:operation GET /repos/search repository repoSearch
|
||||
// ---
|
||||
// summary: Search for repositories
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: q
|
||||
// in: query
|
||||
// description: keyword
|
||||
// type: string
|
||||
// - name: uid
|
||||
// in: query
|
||||
// description: if provided, will return only repos owned by the user with the given id
|
||||
// type: integer
|
||||
// - name: limit
|
||||
// in: query
|
||||
// description: maximum number of repos to return
|
||||
// type: integer
|
||||
// - name: mode
|
||||
// in: query
|
||||
// description: type of repository to search for. Supported values are
|
||||
// "fork", "source", "mirror" and "collaborative"
|
||||
// type: string
|
||||
// - name: exclusive
|
||||
// in: query
|
||||
// description: only search for repositories owned by the authenticated user
|
||||
// type: boolean
|
||||
// responses:
|
||||
// "200":
|
||||
// "$ref": "#/responses/SearchResults"
|
||||
// "422":
|
||||
// "$ref": "#/responses/validationError"
|
||||
opts := &models.SearchRepoOptions{
|
||||
Keyword: strings.Trim(ctx.Query("q"), " "),
|
||||
OwnerID: ctx.QueryInt64("uid"),
|
||||
|
|
@ -187,22 +182,23 @@ func CreateUserRepo(ctx *context.APIContext, owner *models.User, opt api.CreateR
|
|||
|
||||
// Create one repository of mine
|
||||
func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
|
||||
// swagger:route POST /user/repos repository user createCurrentUserRepo
|
||||
//
|
||||
// Consumes:
|
||||
// - application/json
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 201: Repository
|
||||
// 403: forbidden
|
||||
// 422: validationError
|
||||
// 500: error
|
||||
|
||||
// Shouldn't reach this condition, but just in case.
|
||||
// swagger:operation POST /user/repos repository user createCurrentUserRepo
|
||||
// ---
|
||||
// summary: Create a repository
|
||||
// consumes:
|
||||
// - application/json
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: body
|
||||
// in: body
|
||||
// schema:
|
||||
// "$ref": "#/definitions/CreateRepoOption"
|
||||
// responses:
|
||||
// "201":
|
||||
// "$ref": "#/responses/Repository"
|
||||
if ctx.User.IsOrganization() {
|
||||
// Shouldn't reach this condition, but just in case.
|
||||
ctx.Error(422, "", "not allowed creating repository for organization")
|
||||
return
|
||||
}
|
||||
|
|
@ -211,20 +207,30 @@ func Create(ctx *context.APIContext, opt api.CreateRepoOption) {
|
|||
|
||||
// CreateOrgRepo create one repository of the organization
|
||||
func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
|
||||
// swagger:route POST /org/{org}/repos organization createOrgRepo
|
||||
//
|
||||
// Consumes:
|
||||
// - application/json
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 201: Repository
|
||||
// 422: validationError
|
||||
// 403: forbidden
|
||||
// 500: error
|
||||
|
||||
// swagger:operation POST /org/{org}/repos organization createOrgRepo
|
||||
// ---
|
||||
// summary: Create a repository in an organization
|
||||
// consumes:
|
||||
// - application/json
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: org
|
||||
// in: path
|
||||
// description: name of organization
|
||||
// type: string
|
||||
// required: true
|
||||
// - name: body
|
||||
// in: body
|
||||
// schema:
|
||||
// "$ref": "#/definitions/CreateRepoOption"
|
||||
// responses:
|
||||
// "201":
|
||||
// "$ref": "#/responses/Repository"
|
||||
// "422":
|
||||
// "$ref": "#/responses/validationError"
|
||||
// "403":
|
||||
// "$ref": "#/responses/forbidden"
|
||||
org, err := models.GetOrgByName(ctx.Params(":org"))
|
||||
if err != nil {
|
||||
if models.IsErrOrgNotExist(err) {
|
||||
|
|
@ -244,19 +250,21 @@ func CreateOrgRepo(ctx *context.APIContext, opt api.CreateRepoOption) {
|
|||
|
||||
// Migrate migrate remote git repository to gitea
|
||||
func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
|
||||
// swagger:route POST /repos/migrate repository repoMigrate
|
||||
//
|
||||
// Consumes:
|
||||
// - application/json
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 201: Repository
|
||||
// 422: validationError
|
||||
// 500: error
|
||||
|
||||
// swagger:operation POST /repos/migrate repository repoMigrate
|
||||
// ---
|
||||
// summary: Migrate a remote git repository
|
||||
// consumes:
|
||||
// - application/json
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: body
|
||||
// in: body
|
||||
// schema:
|
||||
// "$ref": "#/definitions/MigrateRepoForm"
|
||||
// responses:
|
||||
// "201":
|
||||
// "$ref": "#/responses/Repository"
|
||||
ctxUser := ctx.User
|
||||
// Not equal means context user is an organization,
|
||||
// or is another user/organization if current user is admin.
|
||||
|
|
@ -329,29 +337,44 @@ func Migrate(ctx *context.APIContext, form auth.MigrateRepoForm) {
|
|||
|
||||
// Get one repository
|
||||
func Get(ctx *context.APIContext) {
|
||||
// swagger:route GET /repos/{username}/{reponame} repository repoGet
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 200: Repository
|
||||
// 500: error
|
||||
|
||||
// swagger:operation GET /repos/{owner}/{repo} repository repoGet
|
||||
// ---
|
||||
// summary: Get a repository
|
||||
// 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/Repository"
|
||||
ctx.JSON(200, ctx.Repo.Repository.APIFormat(ctx.Repo.AccessMode))
|
||||
}
|
||||
|
||||
// GetByID returns a single Repository
|
||||
func GetByID(ctx *context.APIContext) {
|
||||
// swagger:route GET /repositories/{id} repository repoGetByID
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 200: Repository
|
||||
// 500: error
|
||||
|
||||
// swagger:operation GET /repositories/{id} repository repoGetByID
|
||||
// ---
|
||||
// summary: Get a repository by id
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: id
|
||||
// in: path
|
||||
// description: id of the repo to get
|
||||
// type: integer
|
||||
// required: true
|
||||
// responses:
|
||||
// "200":
|
||||
// "$ref": "#/responses/Repository"
|
||||
repo, err := models.GetRepositoryByID(ctx.ParamsInt64(":id"))
|
||||
if err != nil {
|
||||
if models.IsErrRepoNotExist(err) {
|
||||
|
|
@ -375,16 +398,27 @@ func GetByID(ctx *context.APIContext) {
|
|||
|
||||
// Delete one repository
|
||||
func Delete(ctx *context.APIContext) {
|
||||
// swagger:route DELETE /repos/{username}/{reponame} repository repoDelete
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 204: empty
|
||||
// 403: forbidden
|
||||
// 500: error
|
||||
|
||||
// swagger:operation DELETE /repos/{owner}/{repo} repository repoDelete
|
||||
// ---
|
||||
// summary: Delete a repository
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: owner
|
||||
// in: path
|
||||
// description: owner of the repo to delete
|
||||
// type: string
|
||||
// required: true
|
||||
// - name: repo
|
||||
// in: path
|
||||
// description: name of the repo to delete
|
||||
// type: string
|
||||
// required: true
|
||||
// responses:
|
||||
// "204":
|
||||
// "$ref": "#/responses/empty"
|
||||
// "403":
|
||||
// "$ref": "#/responses/forbidden"
|
||||
if !ctx.Repo.IsAdmin() {
|
||||
ctx.Error(403, "", "Must have admin rights")
|
||||
return
|
||||
|
|
@ -408,15 +442,25 @@ func Delete(ctx *context.APIContext) {
|
|||
|
||||
// MirrorSync adds a mirrored repository to the sync queue
|
||||
func MirrorSync(ctx *context.APIContext) {
|
||||
// swagger:route POST /repos/{username}/{reponame}/mirror-sync repository repoMirrorSync
|
||||
//
|
||||
// Produces:
|
||||
// - application/json
|
||||
//
|
||||
// Responses:
|
||||
// 200: empty
|
||||
// 403: forbidden
|
||||
|
||||
// swagger:operation POST /repos/{owner}/{repo}/mirror-sync repository repoMirrorSync
|
||||
// ---
|
||||
// summary: Sync a mirrored repository
|
||||
// produces:
|
||||
// - application/json
|
||||
// parameters:
|
||||
// - name: owner
|
||||
// in: path
|
||||
// description: owner of the repo to sync
|
||||
// type: string
|
||||
// required: true
|
||||
// - name: repo
|
||||
// in: path
|
||||
// description: name of the repo to sync
|
||||
// type: string
|
||||
// required: true
|
||||
// responses:
|
||||
// "200":
|
||||
// "$ref": "#/responses/empty"
|
||||
repo := ctx.Repo.Repository
|
||||
|
||||
if !ctx.Repo.IsWriter() {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue