self-hosted/woodpecker
1
0
Fork 0
mirror of https://github.com/woodpecker-ci/woodpecker.git synced 2024-12-12 08:23:48 +02:00
Code Issues Releases Activity
b892f566e5
woodpecker/server/swagger/files/swagger.yml
Brad Rydzewski 0fb4aeda3f bump to 0.5 in master
2016-05-02 12:21:25 -07:00

1037 lines
27 KiB
YAML
Raw Blame History

swagger: "2.0"
info:
version: 1.0.0
title: Drone API
license:
name: Creative Commons 4.0 International
url: "http://creativecommons.org/licenses/by/4.0/"
host: "localhost:8080"
basePath: /api
schemes:
- http
- https
consumes:
- application/json
produces:
- application/json
#
# Operation tags
#
tags:
- name: Repos
- name: Builds
- name: User
- name: Users
#
# Security Definitions
#
security:
- accessToken: []
securityDefinitions:
accessToken:
type: apiKey
in: query
name: access_token
#
# Endpoint Definitions
#
paths:
#
# Repos Endpoint
#
/repos/{owner}/{name}:
get:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
tags:
- Repos
summary: Get a repo
description: Retrieves the details of a repository.
security:
- accessToken: []
responses:
200:
schema:
$ref: "#/definitions/Repo"
404:
description: |
Unable to find the repository.
patch:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
- name: repo
in: body
description: The updated repository JSON
schema:
$ref: '#/definitions/Repo'
example: |
{
"timeout": 60,
"private": false,
"trusted": false,
"allow_pr": true,
"allow_push": true,
"allow_deploys": false,
"allow_tags": false
}
required: true
tags:
- Repos
summary: Updates a repo
description: Updates the specified repository.
security:
- accessToken: []
responses:
200:
schema:
$ref: "#/definitions/Repo"
400:
description: |
Unable to update the repository in the database.
404:
description: |
Unable to find the repository.
post:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
tags:
- Repos
summary: Activates a repo
description: Activates a repository.
security:
- accessToken: []
responses:
200:
schema:
$ref: "#/definitions/Repo"
400:
description: |
Unable to update the Repository record in the database
403:
description: |
Unable to activate the Repository due to insufficient privileges
404:
description: |
Unable to retrieve the Repository from the remote system (ie GitHub)
409:
description: |
Unable to activate the Repository because it is already activate
500:
description: |
Unable to activate the Repository due to an internal server error. This may indicate a problem adding hooks to the remote system (ie Github), generating SSH deployment keys, or persisting to the database.
delete:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
tags:
- Repos
summary: Delete a repo
description: Permanently deletes a repository. It cannot be undone.
security:
- accessToken: []
responses:
200:
description: |
Successfully deleted the Repository
400:
description: |
Unable to remove post-commit hooks from the remote system (ie GitHub)
404:
description: |
Unable to find the Repository in the database
500:
description: |
Unable to update the Repository record in the database
#
# Repos Param Encryption Enpoint
# TODO: properly add the input output schema
/repos/{owner}/{name}/encrypt:
post:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
tags:
- Repos
summary: Encrypt repo secrets
description: Encryptes a Yaml file with secret environment variables for secure public storage.
security:
- accessToken: []
responses:
200:
description: The encrypted parameters.
400:
description: |
Unable to encrypt the parameters.
404:
description: |
Unable to find the repository.
#
# Builds Endpoint
#
/repos/{owner}/{name}/builds:
get:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
tags:
- Builds
summary: Get recent builds
description: Returns recent builds for the repository based on name.
security:
- accessToken: []
responses:
200:
description: The recent builds.
schema:
type: array
items:
$ref: "#/definitions/Build"
404:
description: |
Unable to find the Repository in the database
/repos/{owner}/{name}/builds/{number}:
get:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
- name: number
in: path
type: integer
description: sequential build number
tags:
- Builds
summary: Get a build
description: Returns the repository build by number.
security:
- accessToken: []
responses:
200:
description: The build.
schema:
$ref: "#/definitions/Build"
404:
description: |
Unable to find the Repository or Build
/repos/{owner}/{name}/builds/{number}:
get:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
- name: branch
in: query
type: string
description: name of the branch
required: false
- name: number
in: path
type: integer
description: sequential build number
tags:
- Builds
summary: Get the latest build
description: Returns the latest repository build.
security:
- accessToken: []
responses:
200:
description: The build.
schema:
$ref: "#/definitions/Build"
404:
description: |
Unable to find the Repository or Build
post:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
- name: number
in: path
type: integer
description: sequential build number
tags:
- Builds
summary: Restart a build
description: Restart the a build by number.
security:
- accessToken: []
responses:
200:
description: Successfully restarted the Build.
schema:
$ref: "#/definitions/Build"
404:
description: |
Unable to find the Repository or Build.
409:
description: |
Cannot re-start a Build that is running.
#
# Jobs Endpoint
#
/repos/{owner}/{name}/logs/{number}/{job}:
get:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
- name: number
in: path
type: integer
description: sequential build number
- name: job
in: path
type: integer
description: sequential job number
tags:
- Builds
summary: Get build logs
description: Returns the build logs for a specific job (build step).
produces:
- text/plain
security:
- accessToken: []
responses:
200:
description: The logs for the requested job.
404:
description: |
Unable to find the repository, build or job.
delete:
parameters:
- name: owner
in: path
type: string
description: owner of the repository
- name: name
in: path
type: string
description: name of the repository
- name: number
in: path
type: integer
description: sequential build number
- name: job
in: path
type: integer
description: sequential job number
tags:
- Builds
summary: Cancel a Job
description: Cancel the a build job by number.
security:
- accessToken: []
responses:
200:
description: Successfully cancelled the Job
404:
description: |
Unable to find the Repository or Job
409:
description: |
Cannot cancel a Job that is already stopped
#
# User Endpoint
#
/user:
get:
summary: Gets a user
description: Returns the currently authenticated user.
security:
- accessToken: []
tags:
- User
responses:
200:
description: The currently authenticated user.
schema:
$ref: "#/definitions/User"
patch:
summary: Updates a user
description: Updates the currently authenticated user.
tags:
- User
parameters:
- name: user
in: body
description: Updates to the user.
required: true
schema:
$ref: "#/definitions/User"
responses:
200:
description: The updated user.
schema:
$ref: "#/definitions/User"
400:
description: |
Unable to update the user in the database
#
# User Repos
#
/user/repos:
get:
summary: Get user repos
description: |
Retrieve the currently authenticated User's Repository list
tags:
- User
responses:
200:
schema:
type: array
items:
$ref: "#/definitions/Repo"
400:
description: |
Unable to retrieve Repository list
#
# Users Endpoint
#
/users:
get:
tags:
- Users
summary: Get all users
description: Returns all registered, active users in the system.
security:
- accessToken: []
responses:
200:
description: All registered users.
schema:
type: array
items:
$ref: "#/definitions/User"
/users/{login}:
get:
parameters:
- name: login
in: path
type: string
description: user login
tags:
- Users
summary: Get a user
description: Returns a user with the specified login name.
security:
- accessToken: []
responses:
200:
description: Returns the user.
schema:
$ref: "#/definitions/User"
404:
description: Cannot find user with matching login.
post:
parameters:
- name: login
in: path
type: string
description: user login to activate
tags:
- Users
summary: Create a user
description: Creates a new user account with the specified external login.
security:
- accessToken: []
responses:
201:
description: Returns the created user.
schema:
$ref: "#/definitions/User"
400:
description: |
Error inserting User into the database
patch:
parameters:
- name: login
in: path
type: string
description: user login
- name: user
in: body
description: changes to the user
schema:
$ref: '#/definitions/User'
example: |
{
"email": "octocat@github.com",
"admin": false,
"active": true
}
required: true
tags:
- Users
summary: Update a user
description: Updates an existing user account.
security:
- accessToken: []
responses:
200:
description: Returns the updated user.
schema:
$ref: "#/definitions/User"
400:
description: |
Error updating the User in the database
delete:
parameters:
- name: login
in: path
type: string
description: user login
tags:
- Users
summary: Delete a user
description: Deletes the user with the specified login name.
security:
- accessToken: []
responses:
204:
description: |
Successfully deleted the User
400:
description: |
Error deleting the User from the database
403:
description: |
Cannot delete your own User account
404:
description: |
Cannot find the User
#
# Schema Definitions
#
definitions:
User:
description: The user account.
example: |
{
"id": 1,
"login": "octocat",
"email": "octocat@github.com",
"avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
"admin": false,
"active": true
}
properties:
id:
description: The unique identifier for the account.
type: integer
format: int64
login:
description: The login name for the account.
type: string
email:
description: The email address for the account.
type: string
avatar_url:
description: The url for the avatar image.
type: string
admin:
description: Whether the account has administrative priviledges.
type: boolean
active:
description: Whether the account is currently active.
type: boolean
Repo:
description: A version control repository.
example: |
{
"id": 1,
"scm": "git",
"owner": "octocat",
"name": "hello-world",
"full_name": "octocat/hello-world",
"avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
"link_url": "https://github.com/octocat/hello-world",
"clone_url": "https://github.com/octocat/hello-world.git",
"default_branch": "master",
"timeout": 60,
"private": false,
"trusted": false,
"allow_pr": true,
"allow_push": true,
"allow_deploys": false,
"allow_tags": false
}
properties:
id:
description: The unique identifier for the repository.
type: integer
format: int64
scm:
description: |
The source control management being used.
Currently this is either 'git' or 'hg' (Mercurial).
type: string
owner:
description: The owner of the repository.
type: string
name:
description: The name of the repository.
type: string
full_name:
description: |
The full name of the repository.
This is created from the owner and name of the repository.
type: string
avatar_url:
description: The url for the avatar image.
type: string
link_url:
description: The link to view the repository.
type: string
clone_url:
description: The url used to clone the repository.
type: string
default_branch:
description: The default branch of the repository.
type: string
private:
description: Whether the repository is publicly visible.
type: boolean
trusted:
description: |
Whether the repository has trusted access for builds.
If the repository is trusted then the host network can be used and
volumes can be created.
type: boolean
timeout:
description: The amount of time in minutes before the build is killed.
type: integer
x-dart-type: Duration
allow_pr:
description: Whether pull requests should trigger a build.
type: boolean
allow_push:
description: Whether push events should trigger a build.
type: boolean
allow_deploys:
description: Whether deployment events should trigger a build.
type: boolean
allow_tags:
description: Whether tags should trigger a build.
type: boolean
Build:
description: A build for a repository.
example: |
{
"id": 1,
"number": 1,
"event": "push",
"status": "success",
"created_at": 1443677151,
"enqueued_at": 1443677151,
"started_at": 1443677151,
"finished_at": 1443677255,
"commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
"branch": "master",
"ref": "refs/heads/master",
"remote": "https://github.com/octocat/hello-world.git",
"message": "New line at end of file. --Signed off by Spaceghost",
"timestamp": 1443677255,
"author": "Spaceghost",
"author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
"author_email": "octocat@github.com",
"link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
"jobs": [
{
"id": 1,
"number": 1,
"status": "success",
"enqueued_at": 1443677151,
"started_at": 1443677151,
"finished_at": 1443677255,
"exit_code": 0,
"environment": { "GO_VERSION": "1.4" }
},
{
"id": 2,
"number": 2,
"status": "success",
"enqueued_at": 1443677151,
"started_at": 1443677151,
"finished_at": 1443677255,
"exit_code": 0,
"environment": { "GO_VERSION": "1.5" }
}
]
}
properties:
id:
type: integer
format: int64
number:
description: |
The build number.
This number is specified within the context of the repository the build
belongs to and is unique within that.
type: integer
status:
description: The current status of the build.
$ref: '#definitions/BuildStatus'
created_at:
description: When the build request was received.
type: integer
format: int64
x-dart-type: DateTime
enqueued_at:
description: When the build was enqueued.
type: integer
format: int64
x-dart-type: DateTime
started_at:
description: When the build began execution.
type: integer
format: int64
x-dart-type: DateTime
finished_at:
description: When the build was finished.
type: integer
format: int64
x-dart-type: DateTime
deploy_to:
description: Where the deployment should go.
type: string
commit:
description: The commit for the build.
type: string
branch:
description: The branch the commit was pushed to.
type: string
message:
description: The commit message.
type: string
timestamp:
description: When the commit was created.
type: integer
format: int64
x-dart-format: DateTime
ref:
description: The alias for the commit.
type: string
refspec:
description: The mapping from the local repository to a branch in the remote.
type: string
remote:
description: The remote repository.
type: string
author:
description: The login for the author of the commit.
type: string
author_avatar:
description: The avatar for the author of the commit.
type: string
author_email:
description: The email for the author of the commit.
type: string
link_url:
description: |
The link to view the repository.
This link will point to the repository state associated with the
build's commit.
type: string
jobs:
description: |
The jobs associated with this build.
A build will have multiple jobs if a matrix build was used or if a
rebuild was requested.
type: array
items:
$ref: "#/definitions/Job"
BuildStatus:
description: The status of a build.
type: string
enum:
- success
- failure
- pending
- started
- error
- killed
x-enum-descriptions:
- The build was successful.
- The build failed.
- The build is pending execution.
- The build was started.
- There was an error running the build.
- The build was killed either manually or through a timeout.
Job:
description: A single job being executed as part of a build.
example: |
{
"id": 1,
"number": 1,
"status": "success",
"enqueued_at": 1443677151,
"started_at": 1443677151,
"finished_at": 1443677255,
"exit_code": 0,
"environment": { "GO_VERSION": "1.4" }
}
properties:
id:
description: The unique identifier for the build.
type: integer
format: int64
number:
description: |
The job number.
This number is specified within the context of the build the job
belongs to and is unique within that.
type: integer
status:
description: The current status of the job.
$ref: '#definitions/BuildStatus'
exit_code:
description: The exit code for the build.
type: integer
enqueued_at:
description: When the job was enqueued.
type: integer
format: int64
x-dart-type: DateTime
started_at:
description: When the job began execution.
type: integer
format: int64
x-dart-type: DateTime
finished_at:
description: When the job finished execution.
type: integer
format: int64
x-dart-type: DateTime
environment:
description: |
The environment that the job was run with.
This is a map containing any values for matrix builds.
type: object
Feed:
description: |
A feed entry for a build.
Feed entries can be used to display information on the latest builds.
example: |
{
"owner": "octocat",
"name": "hello-world",
"full_name": "octocat/hello-world",
"number": 1,
"event": "push",
"status": "success",
"created_at": 1443677151,
"enqueued_at": 1443677151,
"started_at": 1443677151,
"finished_at": 1443677255,
"commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
"branch": "master",
"ref": "refs/heads/master",
"remote": "https://github.com/octocat/hello-world.git",
"message": "New line at end of file. --Signed off by Spaceghost",
"timestamp": 1443677255,
"author": "Spaceghost",
"author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
"author_email": "octocat@github.com",
"link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
}
properties:
owner:
description: The owner of the repository.
type: string
name:
description: The name of the repository.
type: string
full_name:
description: |
The full name of the repository.
This is created from the owner and name of the repository.
type: string
number:
description: |
The build number.
This number is specified within the context of the repository the build
belongs to and is unique within that.
type: integer
status:
description: The current status of the build.
$ref: '#definitions/BuildStatus'
created_at:
description: When the build request was received.
type: integer
format: int64
x-dart-type: DateTime
enqueued_at:
description: When the build was enqueued.
type: integer
format: int64
x-dart-type: DateTime
started_at:
description: When the build began execution.
type: integer
format: int64
x-dart-type: DateTime
finished_at:
description: When the build was finished.
type: integer
format: int64
x-dart-type: DateTime
commit:
description: The commit for the build.
type: string
branch:
description: The branch the commit was pushed to.
type: string
message:
description: The commit message.
type: string
timestamp:
description: When the commit was created.
type: integer
format: int64
x-dart-format: DateTime
ref:
description: The alias for the commit.
type: string
refspec:
description: The mapping from the local repository to a branch in the remote.
type: string
remote:
description: The remote repository.
type: string
author:
description: The login for the author of the commit.
type: string
author_avatar:
description: The avatar for the author of the commit.
type: string
author_email:
description: The email for the author of the commit.
type: string
link_url:
description: |
The link to view the repository.
This link will point to the repository state associated with the
build's commit.
type: string
Reference in New Issue View Git Blame Copy Permalink