diff --git a/doc/api.raml b/doc/api.raml
index b4cabeaf8..02d41f03b 100644
--- a/doc/api.raml
+++ b/doc/api.raml
@@ -214,7 +214,7 @@ traits:
responses:
202:
description: |
- Successfully cancelled the Build
+ Successfully restarted the Build
404:
description: |
Cannot find Build by Number
diff --git a/doc/swagger.yml b/doc/swagger.yml
index b717af547..db54008a6 100644
--- a/doc/swagger.yml
+++ b/doc/swagger.yml
@@ -21,11 +21,12 @@ produces:
#
tags:
- - name: repository
- - name: build
- - name: user
- - name: users
- - name: tokens
+ - name: Repos
+ - name: Builds
+ - name: Badges
+ - name: User
+ - name: Users
+ - name: Tokens
#
# Security Definitions
@@ -61,7 +62,7 @@ paths:
type: string
description: name of the repository
tags:
- - repository
+ - Repos
summary: Get a repo
description: Retrieves the details of a repository.
security:
@@ -108,7 +109,7 @@ paths:
}
required: true
tags:
- - repository
+ - Repos
summary: Updates a repo
description: Updates the specified repository.
security:
@@ -135,7 +136,7 @@ paths:
type: string
description: name of the repository
tags:
- - repository
+ - Repos
summary: Creates a repo
description: Creates a new repository.
security:
@@ -171,7 +172,7 @@ paths:
type: string
description: name of the repository
tags:
- - repository
+ - Repos
summary: Delete a repo
description: Permanently deletes a repository. It cannot be undone.
security:
@@ -207,7 +208,7 @@ paths:
type: string
description: name of the repository
tags:
- - repository
+ - Repos
summary: Watch
description: Watches the named repository.
security:
@@ -235,7 +236,7 @@ paths:
type: string
description: name of the repository
tags:
- - repository
+ - Repos
summary: Unwatch
description: Unwatches the repository.
security:
@@ -268,7 +269,7 @@ paths:
type: string
description: name of the repository
tags:
- - build
+ - Builds
summary: Get recent builds
description: Returns recent builds for the repository based on name.
security:
@@ -300,7 +301,7 @@ paths:
type: integer
description: sequential build number
tags:
- - build
+ - Builds
summary: Get a build
description: Returns the repository build by number.
security:
@@ -312,8 +313,102 @@ paths:
$ref: "#/definitions/Build"
404:
description: |
- Unable to find the Build
+ Unable to find the Repository or Build
+ 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
+ tags:
+ - Builds
+ summary: Cancel a build
+ description: Cancel the a build by number.
+ security:
+ - accessToken: []
+ responses:
+ 200:
+ description: Successfully cancelled the Build
+ 404:
+ description: |
+ Unable to find the Repository or Build
+ 409:
+ description: |
+ Cannot cancel a Build that is already stopped
+ 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.
+
+ /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.
#
# Badges
@@ -321,6 +416,11 @@ paths:
/badges/{owner}/{name}/status.svg:
get:
+ tags:
+ - Badges
+ produces:
+ - image/svg+xml
+ summary: Status Badge
description: Returns an SVG status badge for the latest Build
parameters:
- name: owner
@@ -336,9 +436,33 @@ paths:
type: string
description: specify a branch. defaults to master
default: master
-
+ responses:
+ 200:
+ description: Status badge in SVG format
+ examples:
+ image/svg+xml: |
+
+
/badges/{owner}/{name}/cc.xml:
get:
+ tags:
+ - Badges
+ summary: CCMenu
description: Returns a CCMenu feed for the Repository
parameters:
- name: owner
@@ -351,6 +475,26 @@ paths:
description: name of the repository
produces:
- application/xml
+ responses:
+ 200:
+ description: CCMenu XML feed object
+ examples:
+ application/xml: |
+ <Projects>
+ <Project name="octocat/octocat"
+ activity="Sleeping"
+ lastBuildStatus="Success"
+ lastBuildLabel="25"
+ lastBuildTime="2015-06-23T01:58:20-04:00" />
+ </Projects>
+ # application/xml: |
+ #
+ #
+ #
#
# User Endpoint
@@ -363,7 +507,7 @@ paths:
security:
- accessToken: []
tags:
- - user
+ - User
responses:
200:
description: The currently authenticated user.
@@ -373,7 +517,7 @@ paths:
summary: Updates a user
description: Updates the currently authenticated user.
tags:
- - user
+ - User
parameters:
- name: user
in: body
@@ -401,7 +545,7 @@ paths:
description: |
Retrieve the currently authenticated User's Repository list
tags:
- - user
+ - User
responses:
200:
schema:
@@ -419,11 +563,70 @@ paths:
/user/tokens:
get:
+ tags:
+ - Tokens
+ summary: Get all tokens
+ description: Returns all tokens for currently authenticated user.
+ security:
+ - accessToken: []
+ responses:
+ 200:
+ description: All user tokens.
+ schema:
+ type: array
+ items:
+ $ref: "#/definitions/Token"
post:
+ parameters:
+ - name: token
+ description: Token input paraeters.
+ in: body
+ schema:
+ example: |
+ {
+ "label": "my_token"
+ }
+ tags:
+ - Tokens
+ summary: Create a token
+ description: Generates a new user access token.
+ security:
+ - accessToken: []
+ responses:
+ 200:
+ description: The generated user token.
+ schema:
+ $ref: "#/definitions/Token"
+ 400:
+ description: |
+ Error when attempting to generate the JWT token
+ 500:
+ description: |
+ Error when attempting to save the Token
/user/tokens/{label}:
delete:
-
+ parameters:
+ - name: label
+ in: path
+ type: string
+ description: token label
+ tags:
+ - Tokens
+ summary: Delete a token
+ description: Revokes a token with the matching label.
+ security:
+ - accessToken: []
+ responses:
+ 200:
+ description: |
+ Successfully deleted the Token
+ 400:
+ description: |
+ Error attempting to delete Token from database
+ 404:
+ description: |
+ Unable to find Token in database
#
# Users Endpoint
@@ -432,7 +635,7 @@ paths:
/users:
get:
tags:
- - users
+ - Users
summary: Get all users
description: Returns all registered, active users in the system.
security:
@@ -447,9 +650,105 @@ paths:
/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
@@ -459,9 +758,9 @@ definitions:
User:
example: |
{
- "name": "Octocat",
+ "login": "Octocat",
"email": "octocat@github.com",
- "gravatar_id": "7194e8d48fa1d2b689f99443b767316c",
+ "avatar": "7194e8d48fa1d2b689f99443b767316c",
"admin": false,
"active": true
}
@@ -477,6 +776,12 @@ definitions:
active:
type: boolean
Token:
+ example: |
+ {
+ "label":"my_token",
+ "issued_at":1435289846,
+ "hash":"yUQJHM4YfNZcCLlikAshgjM6hCMlFXmHuABAECGsMQ"
+ }
properties:
issued_at:
type: integer