Merge pull request #26 from hainingzhang/master

update Swagger instructions

docs/configure_swagger.md

@@ -1,42 +1,32 @@
-#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.
+# 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
 ```
-### 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_
+### 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
 ```
-* Open script _prepare-swagger.sh_ located at _docs_ directory.
+* Edit the script file _prepare-swagger.sh_ under the _docs_ directory.
 ```sh
   vi prepare-swagger.sh
 ```
-* Change SERVER_IP value with your deployed Harbor node.
+* Change the SERVER_IP to the IP address of your Harbor server.
 ```sh
-  SERVER_ID=10.117.170.69
+  SERVER_ID=<HARBOR_SERVER_DOMAIN>
 ```
-* 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.
+* Run the shell script. It downloads a Swagger package and extracts files into the _static_ directory in Harbor project.
 ```sh
    ./prepare-swagger.sh
 ```
@@ -44,39 +34,41 @@ First, you should checkout the Harbor project from github.
 ```sh
   cd ../Deploy
 ```
-* Open _docker-compose.yml_ file.
+* Edit the _docker-compose.yml_ file.
 ```sh
   vi docker-compose.yml
 ```
-* Add two lines in the _docker-compose.yml_ file at _ui_ _volumes_ configure segment.
+* Add two lines to the file _docker-compose.yml_ under the section _ui.volumes_.
 ```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 .
+* Clean up the previous running version. NOTE: The command does not remove your existing data.
 ```docker
    docker-compose rm
 ```
-* Start new updated Harbor project
+* Start the new Harbor build
 ```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.**
+* 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.
 ```
-  http://10.117.170.69/static/vendors/swagger/index.html
+  http://<HARBOR_SERVER>/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**.
+* 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)