Upstream/harbor
1
0
Fork 0
mirror of https://github.com/goharbor/harbor.git synced 2024-11-22 10:15:35 +01:00
Code Issues Projects Releases Wiki Activity

added configure_swagger.md and shell script.

Browse Source
This commit is contained in:
wknet123 2016-03-10 18:05:12 +08:00
parent bde05a6177
commit c2353f9c2d
3 changed files with 753 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
docs/configure_swagger.md Normal file
View File

@ -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 description 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**.

16
docs/prepare-swagger.sh Executable file
View File

@ -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."

655
docs/swagger.yaml Normal file
View File

@ -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.