harbor/docs/configure_swagger.md

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

   git clone git@github.com:vmware/harbor.git

Listed descriptions only

• Download and untar the Swagger UI release package.

   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

  cd docs

• Open script prepare-swagger.sh located at docs directory.

  vi prepare-swagger.sh

• Change SERVER_IP value with your deployed Harbor node.

  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.

   ./prepare-swagger.sh

• Change the directory to Deploy

  cd ../Deploy

• Open docker-compose.yml file.

  vi docker-compose.yml

• Add two lines in the docker-compose.yml file at ui volumes configure segment.

## 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-compose build

• Clean up left before .

   docker-compose rm

• Start new updated Harbor project

   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.