Upstream/harbor
1
0
Fork 0
mirror of https://github.com/goharbor/harbor.git synced 2024-12-25 10:07:43 +01:00
Code Issues Projects Releases Wiki Activity
bcc6a4bbf2
harbor/docs/configure_swagger.md

2.8 KiB
Raw Blame History

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:

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

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

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.
  cd docs
  • Edit the script file prepare-swagger.sh under the docs directory.
  vi prepare-swagger.sh
  • Change the SCHEME to the protocol scheme of your Harbor server.
  SCHEME=<HARBOR_SERVER_SCHEME>
  • Change the SERVER_IP to the IP address of your Harbor server.
  SERVER_ID=<HARBOR_SERVER_DOMAIN>
  • Run the shell script. It downloads a Swagger package and extracts files into the static directory in Harbor project.
   ./prepare-swagger.sh
  • Change the directory to make
  cd ../make/dev
  • Edit the docker-compose.yml file.
  vi docker-compose.yml
  • Add two lines to the file docker-compose.yml under the section ui.volumes.
...
ui:
  ... 
  volumes:
    - ./config/ui/app.conf:/etc/ui/app.conf
    - ./config/ui/private_key.pem:/etc/ui/private_key.pem
    ## add two lines as below ##
    - ../../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
    ...
  • Rebuild Harbor project
    docker-compose build
  • Clean up the previous running version. NOTE: The command does not remove your existing data.
   docker-compose rm
  • Start the new Harbor build
   docker-compose up
  • 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://<HARBOR_SERVER>/static/vendors/swagger/index.html
  • 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