harbor/docs/configure_swagger.md

79 lines
2.8 KiB
Markdown
Raw Normal View History

2016-03-17 06:01:55 +01:00
# View and test Harbor REST API via Swagger
A Swagger file is provided for viewing and testing Harbor REST API. First, you should get the source code of Harbor:
```sh
git clone git@github.com:vmware/harbor.git
```
2016-03-17 06:01:55 +01:00
### Viewing Harbor REST API
* Open the file **swagger.yaml** under the _docs_ directory in Harbor project;
* Paste all its content into the online Swagger Editor at http://editor.swagger.io. The descriptions of Harbor API will be shown on the right pane of the page.
![Swagger Editor](img/swaggerEditor.png)
### Testing Harbor REST API
From time to time, you may need to mannually test Harbor REST API. You can deploy the Swagger file into Harbor's service node.
**Caution:** When using Swagger to send REST requests to Harbor, you may alter the data of Harbor accidentally. For this reason, it is NOT recommended using Swagger against a production Harbor instance.
* Change the directory to _docs_ in Harbor project.
```sh
cd docs
```
2016-03-17 06:01:55 +01:00
* Edit the script file _prepare-swagger.sh_ under the _docs_ directory.
```sh
vi prepare-swagger.sh
```
2016-04-26 17:35:12 +02:00
* Change the SCHEME to the protocol scheme of your Harbor server.
```sh
SCHEME=<HARBOR_SERVER_SCHEME>
```
2016-03-17 06:01:55 +01:00
* Change the SERVER_IP to the IP address of your Harbor server.
```sh
2016-03-17 06:01:55 +01:00
SERVER_ID=<HARBOR_SERVER_DOMAIN>
```
2016-03-17 06:01:55 +01:00
* Run the shell script. It downloads a Swagger package and extracts files into the _static_ directory in Harbor project.
```sh
./prepare-swagger.sh
```
2016-10-19 08:32:00 +02:00
* Change the directory to _make_
```sh
cd ../make/dev
```
2016-03-17 06:01:55 +01:00
* Edit the _docker-compose.yml_ file.
```sh
vi docker-compose.yml
```
2016-03-17 06:01:55 +01:00
* Add two lines to the file _docker-compose.yml_ under the section _ui.volumes_.
```docker
2016-03-17 06:01:55 +01:00
...
ui:
2016-03-17 06:01:55 +01:00
...
volumes:
- ./config/ui/app.conf:/etc/ui/app.conf
- ./config/ui/private_key.pem:/etc/ui/private_key.pem
## add two lines as below ##
2016-10-19 08:32:00 +02:00
- ../../src/ui/static/vendors/swagger-ui-2.1.4/dist:/go/bin/static/vendors/swagger
- ../../src/ui/static/resources/yaml/swagger.yaml:/go/bin/static/resources/yaml/swagger.yaml
2016-03-17 06:01:55 +01:00
...
```
* Rebuild Harbor project
```docker
docker-compose build
```
2016-03-17 06:01:55 +01:00
* Clean up the previous running version. NOTE: The command does not remove your existing data.
```docker
docker-compose rm
```
2016-03-17 06:01:55 +01:00
* Start the new Harbor build
```docker
docker-compose up
```
2016-03-17 06:01:55 +01:00
* Because a session ID is usually required by Harbor API, **you should log in first from a browser.**
* Open another tab in the same browser so that the session is shared between tabs.
* Enter the URL of the Swagger page in Harbor as below. The ```<HARBOR_SERVER>``` should be replaced by the IP address or the hostname of the Harbor server.
```
2016-03-17 06:01:55 +01:00
http://<HARBOR_SERVER>/static/vendors/swagger/index.html
```
2016-03-17 06:01:55 +01:00
* You should see a Swagger UI page with Harbor API _swagger.yaml_ file loaded in the same domain, **be aware that your REST request submitted by Swagger may change the data of Harbor**.
![Harbor API](img/renderedSwagger.png)