refactoring swagger

2026-04-18 10:53:21 +02:00 · 2015-12-08 15:58:05 +09:00
parent 26ad95a36e
commit 9de5ba5fae
5 changed files with 234 additions and 148 deletions
--- a/lib/units/api/swagger/api_v1.yaml
+++ b/lib/units/api/swagger/api_v1.yaml
@@ -2,12 +2,12 @@ swagger: "2.0"
 info:
  version: "2.0.0"
  title: Smartphone Test Farm
-  description: Control and manager real Smartphone devices from browser and restful apis
+  description: Control and manages real Smartphone devices from browser and restful apis
  license:
    name: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  contact:
-    name: STF Support
+    name: STF Team
    email: contact@openstf.io
    url: http://openstf.io/
 basePath: /api/v1
@@ -21,15 +21,15 @@ produces:
 tags:
  - name: user
    description: User Operations
-  - name: device
+  - name: devices
    description: Device Operations
 paths:
  /user:
    x-swagger-router-controller: user
    get:
      summary: User Profile
-      description: The User Profile endpoint returns information about current authorized user.
-      operationId: getCurrentUser
+      description: The User Profile endpoint returns information about current authorized user
+      operationId: getUser
      tags:
        - user
      responses:
@@ -47,13 +47,19 @@ paths:
    x-swagger-router-controller: user
    get:
      summary: List devices owned by current user
-      description: The User Devices endpoint returns information about user group of current authorized user.
-      operationId: getCurrentUserDevices
+      description: The User Devices endpoint returns device list owner by current authorized user
+      operationId: getUserDevices
      tags:
        - user
+      parameters:
+        - name: fields
+          in: query
+          description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response
+          required: false
+          type: string
      responses:
        "200":
-          description: Current User Devices information
+          description: Current User Devices List
          schema:
            $ref: "#/definitions/DeviceListResponse"
        default:
@@ -63,21 +69,23 @@ paths:
      security:
        - accessTokenAuth: []
    post:
-      summary: Add device to a user
-      description: The User Devices endpoint will request stf server for a new device. It will return request accepted if device is usable.
-      operationId: addDeviceToUser
+      summary: Add a device to a user
+      description: The User Devices endpoint will request stf server for a new device. It will return request accepted if device is usable
+      operationId: addUserDevice
      tags:
        - user
      parameters:
-        - name: device
+        - name: devices
          in: body
          description: Device to add
          required: true
          schema:
-            $ref: "#/definitions/DeviceAddPayload"
+            $ref: "#/definitions/AddUserDevicePayload"
      responses:
        "202":
-          description: Device Add Request Status
+          description: Add User Device Request Status and polling Url
+          schema:
+            $ref: "#/definitions/AddUserDeviceResponse"
        default:
          description: Unexpected Error
          schema:
@@ -88,7 +96,7 @@ paths:
    x-swagger-router-controller: user
    get:
      summary: Device Information
-      description: The device enpoint return information about a single device.
+      description: The device enpoint return information about device owned by user
      operationId: getUserDeviceBySerial
      tags:
        - user
@@ -105,9 +113,9 @@ paths:
          type: string
      responses:
        "200":
-          description: Device Information
+          description: Delete User Device Request Status and polling Url
          schema:
-            $ref: "#/definitions/DeviceResponse"
+            $ref: "#/definitions/DeleteUserDeviceBySerialResponse"
        default:
          description: Unexpected Error
          schema:
@@ -116,8 +124,8 @@ paths:
        - accessTokenAuth: []
    delete:
      summary: Release device from user
-      description: The User Devices endpoint will request for device release from stf server.
-      operationId: deleteDeviceFromUser
+      description: The User Devices endpoint will request for device release from stf server. It will return request accepted if device is being used by current user
+      operationId: deleteUserDeviceBySerial
      tags:
        - user
      parameters:
@@ -142,7 +150,7 @@ paths:
    post:
      summary: Remote Connect
      description: The device connect endpoint will request stf server to connect remotely
-      operationId: connectDeviceBySerial
+      operationId: remoteConnectUserDeviceBySerial
      tags:
        - user
      parameters:
@@ -153,7 +161,9 @@ paths:
          type: string
      responses:
        "202":
-          description: Device Connect Request Status
+          description: Remote Connect User Device Request Status
+          schema:
+            $ref: "#/definitions/RemoteConnectUserDeviceResponse"
        default:
          description: Unexpected Error
          schema:
@@ -163,7 +173,7 @@ paths:
    delete:
      summary: Remote Disconnect
      description: The device connect endpoint will request stf server to disconnect remotely
-      operationId: disconnectDeviceBySerial
+      operationId: remoteDisconnectUserDeviceBySerial
      tags:
        - user
      parameters:
@@ -174,7 +184,9 @@ paths:
          type: string
      responses:
        "202":
-          description: Device Disconnect Request Status
+          description: Remote Disonnect User Device Request Status
+          schema:
+            $ref: "#/definitions/RemoteDisconnectUserDeviceResponse"
        default:
          description: Unexpected Error
          schema:
@@ -185,8 +197,8 @@ paths:
    x-swagger-router-controller: token
    get:
      summary: Access Tokens
-      description: The Access Tokens endpoints returns titles of all the valid access tokens.
-      operationId: getAccessTokens
+      description: The Access Tokens endpoints returns titles of all the valid access tokens
+      operationId: getUserAccessTokens
      tags:
        - user
      responses:
@@ -201,13 +213,19 @@ paths:
      security:
        - accessTokenAuth: []
  /devices:
-    x-swagger-router-controller: device
+    x-swagger-router-controller: devices
    get:
      summary: Device List
-      description: The devices enpoint return list of all the STF devices including Disconnected and Offline
+      description: The devices endpoint return list of all the STF devices including Disconnected and Offline
      operationId: getDevices
      tags:
-        - device
+        - devices
+      parameters:
+        - name: fields
+          in: query
+          description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response
+          required: false
+          type: string
      responses:
        "200":
          description: List of Devices
@@ -220,13 +238,13 @@ paths:
      security:
        - accessTokenAuth: []
  /devices/{serial}:
-    x-swagger-router-controller: device
+    x-swagger-router-controller: devices
    get:
      summary: Device Information
-      description: The device enpoint return information about a single device.
+      description: The device enpoint return information about a single device
      operationId: getDeviceBySerial
      tags:
-        - device
+        - devices
      parameters:
        - name: serial
          in: path
@@ -280,13 +298,37 @@ definitions:
    properties:
      device:
        type: object
+  AddUserDeviceResponse:
+    required:
+      - pollingUrl
+    properties:
+      pollingUrl:
+        type: string
+  DeleteUserDeviceBySerialResponse:
+    required:
+      - pollingUrl
+    properties:
+      pollingUrl:
+        type: string
+  RemoteDisconnectUserDeviceResponse:
+    required:
+      - pollingUrl
+    properties:
+      pollingUrl:
+        type: string
+  RemoteConnectUserDeviceResponse:
+    required:
+      - pollingUrl
+    properties:
+      pollingUrl:
+        type: string
  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
-  DeviceAddPayload:
+  AddUserDevicePayload:
    description: payload object for adding device to user
    required:
      - serial
@@ -295,11 +337,11 @@ definitions:
        description: Device Serial
        type: string
      timeout:
-        description: Device timeout in ms. If device is kept idle for this period, it will be automatically disconnected. Default is provider group timeout.
+        description: Device timeout in ms. If device is kept idle for this period, it will be automatically disconnected. Default is provider group timeout
        type: integer

 securityDefinitions:
  accessTokenAuth:
    type: apiKey
-    name: accessTokenAuth
+    name: authorization
    in: header