first draft swaggger spec, complete

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

doc/swagger.yml

@@ -21,11 +21,12 @@ produces:
 #
 
 tags:
-  - name: repository
+  - name: Repos
-  - name: build
+  - name: Builds
-  - name: user
+  - name: Badges
-  - name: users
+  - name: User
-  - name: tokens
+  - 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