darkkirb/harness-drone
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

first draft swaggger spec, complete

Browse source
This commit is contained in:
Brad Rydzewski 2015-07-01 23:22:05 -07:00
parent a0ae4debc9
commit 342e78a16b
2 changed files with 328 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/api.raml
View file

@ -214,7 +214,7 @@ traits:
responses:
202:
description: |
Successfully cancelled the Build
Successfully restarted the Build
404:
description: |
Cannot find Build by Number

349
doc/swagger.yml
View file

@ -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: |
<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg" width="91" height="20">
<linearGradient id="a" x2="0" y2="100%">
<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
<stop offset="1" stop-opacity=".1"/>
</linearGradient>
<rect rx="3" width="91" height="20" fill="#555"/>
<rect rx="3" x="37" width="54" height="20" fill="#4c1"/>
<path fill="#4c1" d="M37 0h4v20h-4z"/>
<rect rx="3" width="91" height="20" fill="url(#a)"/>
<g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
<text x="19.5" y="15" fill="#010101" fill-opacity=".3">build</text>
<text x="19.5" y="14">build</text>
<text x="63" y="15" fill="#010101" fill-opacity=".3">success</text>
<text x="63" y="14">success</text>
</g>
</svg>
/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: |
&lt;Projects&gt;
&lt;Project name=&quot;octocat/octocat&quot;
activity=&quot;Sleeping&quot;
lastBuildStatus=&quot;Success&quot;
lastBuildLabel=&quot;25&quot;
lastBuildTime=&quot;2015-06-23T01:58:20-04:00&quot; /&gt;
&lt;/Projects&gt;
# application/xml: |
# <Projects>
# <Project name="octocat/octocat"
# activity="Sleeping"
# lastBuildStatus="Success"
# lastBuildLabel="25"
# lastBuildTime="2015-06-23T01:58:20-04:00" />
# </Projects>
#
# 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