Merge pull request #20 from wknet123/master

add configurations of swagger

docs/configure_swagger.md

@@ -0,0 +1,82 @@
+#Configure Swagger for Harbor API#
+As for manipulating and documenting Harbor project APIs, we created it by using Swagger.
+## Two forms of demonstration
+There are two forms of demonstration of Swagger UI for Harbor API.
+### Listed descriptions only
+It means you only need to locate the YAML file of Harbor APIs in Swagger UI, 
+then a listed descriptions will be shown. It doesn't affect the deployed Harbor project node actually.
+### Full functions provided by Swagger
+This form of use is a bit of difficult, because it must bind to an available Harbor project node in order to solve the problem of CORS. Well, it will provide full functions accompany with Harbor project node, you must be careful of your operations to avoid damaging backend data.
+## Detail instructions for each
+First, you should checkout the Harbor project from github.
+```sh
+   git clone git@github.com:vmware/harbor.git
+```
+### Listed descriptions only
+* Download and untar the Swagger UI release package.
+```sh
+   wget https://github.com/swagger-api/swagger-ui/archive/v2.1.4.tar.gz \
+     -O swagger.tar.gz
+   tar -zxf swagger.tar.gz swagger-ui-2.1.4/dist
+```
+* Open the _index.html_ file with a browser, input the file path URL of the _swagger.yaml_ file onto Swagger UI page, then click _Explore_ button.
+```
+ file:///root/harbor/docs/swagger.yaml
+```
+### Full functions provided by Swagger UI
+* Change the directory to _docs_
+```sh
+  cd docs
+```
+* Open script _prepare-swagger.sh_ located at _docs_ directory.
+```sh
+  vi prepare-swagger.sh
+```
+* Change SERVER_IP value with your deployed Harbor node.
+```sh
+  SERVER_ID=10.117.170.69
+```
+* Execute this shell script. It helps you to download a Swagger UI release package, untar it into the static files directory of the Harbor project.
+```sh
+   ./prepare-swagger.sh
+```
+* Change the directory to _Deploy_
+```sh
+  cd ../Deploy
+```
+* Open _docker-compose.yml_ file.
+```sh
+  vi docker-compose.yml
+```
+* Add two lines in the _docker-compose.yml_ file at _ui_ _volumes_ configure segment.
+```docker
+## omit other lines ##
+ui:
+  ## omit other lines ##
+  volumes:
+    - ./config/ui/app.conf:/etc/ui/app.conf
+    - ./config/ui/private_key.pem:/etc/ui/private_key.pem
+    ## add two lines as below ##
+    - ../static/vendors/swagger-ui-2.1.4/dist:/go/bin/static/vendors/swagger
+    - ../static/resources/yaml/swagger.yaml:/go/bin/static/resources/yaml/swagger.yaml
+  ## omit other lines ##
+```
+* Rebuild Harbor project
+```docker
+    docker-compose build
+```
+* Clean up left before .
+```docker
+   docker-compose rm
+```
+* Start new updated Harbor project
+```docker
+   docker-compose up
+```
+* Because session ID is required for using Harbor APIs. **You should log in first from UI by using a browser.**
+* Open another tab in the current browser to keep one session.
+* Input the URL deployed by Harbor project. **You should change the IP address with your deployed Harbor project node.**
+```
+  http://10.117.170.69/static/vendors/swagger/index.html
+```
+* Then you should see a Swagger UI deployed by Harbor project, loaded a _swagger.yaml_ file in the same domain, it works actually, **be careful of your operations to avoid damaging backend data**.

docs/prepare-swagger.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+SERVER_IP=10.117.170.65
+set -e
+echo "Doing some clean up..."
+rm -f *.tar.gz
+echo "Downloading Swagger UI release package..."
+wget https://github.com/swagger-api/swagger-ui/archive/v2.1.4.tar.gz -O swagger.tar.gz
+echo "Untarring Swagger UI package to the static file path..."
+tar -C ../static/vendors -zxf swagger.tar.gz swagger-ui-2.1.4/dist
+echo "Executing some processes..."
+sed -i 's/http:\/\/petstore\.swagger\.io\/v2\/swagger\.json/http:\/\/'$SERVER_IP'\/static\/resources\/yaml\/swagger\.yaml/g' \
+ ../static/vendors/swagger-ui-2.1.4/dist/index.html
+mkdir -p ../static/resources/yaml
+cp swagger.yaml ../static/resources/yaml
+sed -i 's/host: localhost/host: '$SERVER_IP'/g' ../static/resources/yaml/swagger.yaml
+echo "Finish preparation for the Swagger UI."

docs/swagger.yaml

@@ -0,0 +1,655 @@
+# this is an example of the Uber API
+# as a demonstration of an API spec in YAML
+swagger: '2.0'
+info:
+  title: Harbor API
+  description: These APIs provide services for manipulating Harbor project.
+  version: "0.1.0"
+# the domain of the service
+host: localhost
+# array of all schemes that your API supports
+schemes:
+  - http
+basePath: /api
+produces:
+  - application/json
+  - text/plain
+consumes:
+  - text/plain
+  - application/json
+paths:
+  /search:
+    get:
+      summary: Search for projects and repositories
+      description: |
+        The Search endpoint returns information about the projects and repositories
+        offered at public status or related to the current logged in user. The
+        response includes the project and repository list in a proper
+        display order.
+      parameters:
+        - name: q
+          in: query
+          description: Search parameter for project and repository name.
+          required: true
+          type: string
+          format: string
+      tags:
+        - Products
+      responses:
+        200:
+          description: An array of search results
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Search'
+        500:
+          description: Unexpected internal errors.
+  /projects:
+    get:
+      summary: Return projects created by Harbor
+      description: |
+        This endpoint returns all projects created by Harbor, and can be filtered by project name.
+      parameters:
+        - name: project_name 
+          in: query
+          description: Project name for filtering results.
+          required: false
+          type: string
+          format: string
+        - name: is_public
+          in: query
+          description: Public sign for filtering projects.
+          required: false
+          type: integer
+          format: int32
+      tags:
+        - Products
+      responses:
+        200:
+          description: Return all matched projects.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Project'
+        500:
+          description: Internal errors.
+    head:
+      summary: Check if the project name user provided already exists.
+      description: |
+        This endpoint is used to check if the project name user provided already exist.
+      parameters:
+        - name: project_name
+          in: query
+          description: Project name for checking exists.
+          required: true
+          type: string
+          format: string
+      tags:
+        - Products
+      responses:
+        200:
+          description: Project name exists.
+        401:
+          description: User need to log in first.
+        404:
+          description: Project name does not exist.
+        500:
+          description: Unexpected internal errors.
+    post:
+      summary: Create a new project.
+      description: |
+        This endpoint is for user to create a new project.
+      parameters:
+        - name: project
+          in: body
+          description: New created project.
+          required: true
+          schema:
+            $ref: '#/definitions/Project'
+      tags:
+        - Products
+      responses:
+        200:
+          description: Project created successfully.
+        400:
+          description: Unsatisfied with constraints of the project creation.
+        401:
+          description: User need to log in first.
+        409:
+          description: Project name already exists.
+        500:
+          description: Unexpected internal errors.
+  /projects/{project_id}:
+    put:
+      summary: Update properties for a selected project.
+      description: |
+        This endpoint is aimed to toggle a project publicity status.
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Selected project ID.
+        - name: project
+          in: body
+          required: true 
+          schema:
+            $ref: '#/definitions/Project'
+          description: Updates of project.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Updated project publicity status successfully.
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        403:
+          description: User does not have permission to the project.
+        404:
+          description: Project ID does not exist.
+        500:
+          description: Unexpected internal errors.
+  /projects/{project_id}/logs/filter:
+    post:
+      summary: Get access logs accompany with a relevant project.
+      description: |
+        This endpoint let user search access logs filtered by operations and date time ranges.
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID
+        - name: access_log
+          in: body
+          schema:
+            $ref: '#/definitions/AccessLog'
+          description: Search results of access logs.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Get access log successfully.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/AccessLog'
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        500:
+          description: Unexpected internal errors.
+  /projects/{project_id}/members/:
+    get:
+      summary: Return a project's relevant role members.
+      description: |
+        This endpoint is for user to search a specified project's relevant role members.
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Get project's relevant role members successfully.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Role'
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        403:
+          description: User in session does not have permission to the project.
+        404:
+          description: Project ID does not exist.
+        500:
+          description: Unexpected internal errors.
+  /projects/{project_id}/members/{user_id}:
+    get:
+      summary: Return role members accompany with relevant project and user.
+      description: |
+        This endpoint is for user to get role members accompany with relevant project and user. 
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID
+        - name: user_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant user ID
+      tags:
+        - Products
+      responses:
+        200:
+          description: Get project role members successfully.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Role'
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        403:
+          description: User in session does not have permission to the project.
+        404:
+          description: Project ID does not exist.
+        500:
+          description: Unexpected internal errors.
+    put:
+      summary: Update project role members accompany with relevant project and user.
+      description: |
+        This endpoint is for user to update current project role members accompany with relevant project and user.
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID.
+        - name: user_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant user ID.
+        - name: roles
+          in: body
+          schema:
+            $ref: '#/definitions/RoleParam'
+          description: Updates for roles and username.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Project role members updated successfully.
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        403:
+          description: User in session does not have permission to the project.
+        404:
+          description: Project ID does not exist.
+        500:
+          description: Unexpected internal errors.      
+    delete:
+      summary: Delete project role members accompany with relevant project and user.
+      description: |
+        This endpoint is aimed to remove project role members already added to the relevant project and user.
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID.
+        - name: user_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant user ID.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Project role members deleted successfully.
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        403:
+          description: User in session does not have permission to the project.
+        404:
+          description: Project ID does not exist.
+        500:
+          description: Unexpected internal errors.   
+  /projects/{project_id}/members/:
+    post:
+      summary: Add project role member accompany with relevant project and user.
+      description: |
+        This endpoint is for user to add project role member accompany with relevant project and user.
+      parameters:
+        - name: project_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID.
+        - name: roles
+          in: body
+          description: Role members for adding to relevant project.
+          schema: 
+            $ref: '#/definitions/RoleParam'
+      tags:
+        - Products
+      responses:
+        200:
+          description: Role members added to relevant project successfully.
+        400:
+          description: Illegal format of provided ID value.
+        401:
+          description: User need to log in first.
+        403:
+          description: User in session does not have permission to the project.
+        404:
+          description: Project ID or username does not exist.
+        409:
+          description: User has already added as a project role member.
+        500:
+          description: Unexpected internal errors.
+  /users:
+    get:
+      summary: Get registered users of Harbor.
+      description: |
+        This endpoint is for user to search registered users, support for filtering results with username.Notice, by now this operation is only for administrator.
+      parameters:
+        - name: user_name
+          in: query
+          type: string
+          format: string
+          required: false
+          description: Username for filtering results.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Searched for users of Harbor successfully.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/User'
+        400:
+          description: Invalid user ID.
+        401:
+          description: User need to log in first.
+        403:
+          description: User does not have permission of admin role.
+        500:
+          description: Unexpected internal errors.
+  /users/{user_id}:
+    put:
+      summary: Update a registered user to change to be an administrator of Harbor.
+      description: |
+        This endpoint let a registered user change to be an administrator
+        of Harbor.
+      parameters:
+        - name: user_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: Registered user ID
+      tags:
+        - Products
+      responses:
+        200:
+          description: Updated user's admin role successfully.
+        400:
+          description: Invalid user ID.
+        401:
+          description: User need to log in first.
+        403:
+          description: User does not have permission of admin role.
+        404:
+          description: User ID does not exist.
+        500:
+          description: Unexpected internal errors.
+    delete:
+      summary: Mark a registered user as be removed.
+      description: |
+        This endpoint let administrator of Harbor mark a registered user as
+        be removed.It actually won't be deleted from DB.
+      parameters:
+        - name: user_id
+          in: path
+          type: integer
+          format: int32
+          required: true
+          description: User ID for marking as to be removed.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Marked user as be removed successfully.
+        400:
+          description: Invalid user ID.
+        401:
+          description: User need to log in first.
+        403:
+          description: User does not have permission of admin role.
+        404:
+          description: User ID does not exist.
+        500:
+          description: Unexpected internal errors.
+  /repositories:
+    get:
+      summary: Get repositories accompany with relevant project and repo name.
+      description: |
+        This endpoint let user search repositories accompanying with relevant project ID and repo name.
+      parameters:
+        - name: project_id
+          in: query
+          type: integer
+          format: int32
+          required: true
+          description: Relevant project ID.
+        - name: q
+          in: query
+          type: string
+          format: string
+          required: false
+          description: Repo name for filtering results.
+      tags:
+        - Products
+      responses:
+        200:
+          description: Searched for respositories successfully.
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Repository'
+        400:
+          description: Invalid project ID.
+        403:
+          description: Project is not public or current user is irrelevant to the repository.
+        404:
+          description: Project ID does not exist.
+        500:
+          description: Unexpected internal errors.
+  /repositories/tags:
+    get:
+      summary: Get tags of a relevant repository.
+      description: |
+        This endpoint aims to retrieve tags from a relevant repository.
+      parameters:
+        - name: repo_name
+          in: query
+          type: string
+          required: true
+          description: Relevant repository name.
+      tags:
+       - Products
+      responses:
+        200:
+          description: Retrieved tags from a relevant repository successfully.
+        500:
+          description: Unexpected internal errors.
+  /repositories/manifest:
+    get:
+      summary: Get manifests of a relevant repository.
+      description: |
+        This endpoint aims to retreive manifests from a relevant repository.
+      parameters:
+        - name: repo_name
+          in: query
+          type: string
+          required: true
+          description: Repository name
+        - name: tag
+          in: query
+          type: string
+          required: true
+          description: Tag name
+      tags:
+        - Products
+      responses:
+        200:
+          description: Retrieved manifests from a relevant repository successfully.
+        500:
+          description: Unexpected internal errors.
+definitions:
+  Search:
+    type: object
+    properties:
+      projects:
+        description: Search results of the projects that matched the filter keywords.
+        type: array
+        items:
+          $ref: '#/definitions/Project'
+      repositories:
+        description: Search results of the repositories that matched the filter keywords.
+        type: array
+        items:
+          $ref: '#/definitions/Repository'
+  Project:
+    type: object
+    properties:
+      project_id:
+        type: integer
+        format: int32
+        description: Project ID
+      owner_id:
+        type: integer
+        format: int32
+        description: The owner ID of the project always means the creator of the project.
+      project_name:
+        type: string
+        description: The name of the project.
+      creation_time:
+        type: string
+        description: The creation time of the project.
+      deleted:
+        type: integer
+        format: int32
+        description: A deletion mark of the project.
+      user_id:
+        type: integer
+        format: int32
+        description: A relation field to the user table.
+      owner_name:
+        type: string
+        description: The owner name of tthe project always means the creator of the project.
+      public:
+        type: boolean
+        format: boolean
+        description: The public status of the project.
+      togglable:
+        type: boolean
+        description: Correspond to the UI about showing the public status of the project.
+  Repository:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Repository ID
+      parent:
+        type: string
+        description: Parent of the image.
+      created:
+        type: string
+        format: date-time
+        description: Repository create time.
+      duration_days:
+        type: string
+        description: Duration days of the image.
+      author:
+        type: string
+        description: Author of the image.
+      architecture:
+        type: string
+        description: Architecture of the image.
+      docker_version:
+        type: string
+        description: Docker version of the image.
+      os:
+        type: string
+        description: OS of the image.
+  User:
+    type: object
+    properties:
+      user_id:
+        type: integer
+        format: int32
+      username:
+        type: string
+      email:
+        type: string
+      password: 
+        type: string
+      realname: 
+        type: string
+      comment:
+        type: string
+      deleted:
+        type: integer
+        format: int32
+  AccessLog:
+    type: object
+    properties:
+      username:
+        type: string
+        description: Relevant user's name that accessed this project.
+      keywords:
+        type: string
+        description: Operation name specified when project created.
+      beginTimestamp:
+        type: integer
+        format: int32
+        description: Begin timestamp for querying access logs.
+      endTimestamp:
+        type: integer
+        format: int32
+        description: End timestamp for querying accessl logs.
+  Role:
+    type: object
+    properties:
+      role_id: 
+        type: integer
+        format: int32
+        description: ID in table.
+      role_code: 
+        type: string
+        description: Description of permissions for the role.
+      role_name:
+        type: string
+        description: Name the the role.
+  RoleParam:
+    type: object
+    properties:
+      roles:
+        type: array
+        items:
+          type: integer  
+          format: int32
+        description: Role ID for updating project role member.
+      user_name:
+        type: string
+        description: Username relevant to a project role member.