Google Git
Sign in
apache / trafficcontrol / refs/heads/4.1.x / . / traffic_ops / traffic_ops_golang / swaggerdocs / v13
tree: edffd3c43eda2f75e6ed411a7419c268d6a01b24 [path history] [tgz]
  1. swaggerspec/
  2. swaggerspec-server/
  3. .gitignore
  4. alerts.go
  5. asns.go
  6. cdns.go
  7. divisions.go
  8. docker-compose.yml
  9. Dockerfile
  10. docs.go
  11. gen_swaggerspec.sh
  12. physlocations.go
  13. profileparameters.go
  14. profiles.go
  15. README.md
  16. regions.go
  17. statuses.go
traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md

./swaggerdocs overview

This directory contains the Go structs that glue together the Swagger 2.0 metadata that will generate the Traffic Ops API documentation using the go-swagger meta tags. The Traffic Ops API documentation is maintained by modifying the Go files in this directory and the Go structs that they reference from here trafficcontrol/lib/go-tc/*.go. These combination of these two areas of .go files will produce Swagger documentation for the Traffic Ops Go API's.

Setup

Generating your Swagger Spec File

The gen_swaggerspec.sh script will scan all the Go files in the swaggerdocs directory and extract out all of the swagger meta tags that are embedded as comments. The output of the gen_swaggerspec.sh script will be the swaggerspec/swagger.json spec file.

While the Docker services are running, just re-run gen_swaggerspec.sh and hit refresh on the page to see the Swagger doc updates in real time.

Running the web services

Once your swaggerspec/swagger.json file has been generated you will want to render it to verify it's contents with the HTTP web rendering services.

The docker-compose.yml will start two rendering services, a custom http service for hosting the swaggerspec/swagger.json and the Swagger UI.

To start the Swagger UI services (and build them if not already built) just run:

$ docker-compose up

NOTE: Iterative Workflow Tips:

Blow away only the local images (excluding remote ones) and bring down the container: $ docker-compose down --rmi local

Blow away all the images (including remote ones) and bring down the container: $ docker-compose down --rmi all

Once started navigate your browser to http://localhost:8080

Converting the swaggerspec/swagger.json to .rst

After you generate the swaggerspec/swagger.json from the steps above use the swaggerspec Docker Compose file to convert the swagger.json to .rst so that it can merged in with the existing Traffic Control documentation.

  • $ cd swaggerspec
  • $ docker-compose up - will convert the swagger.json in this directory into v13_api_docs.rst
  • $ cp v13_api_docs.rst ../../../../../docs/source/development/traffic_ops_api
  • $ cd ../../../../../docs
  • $ make - will generate all the Sphinx documentation along with the newly generated TO Swagger API 1.3 docs

NOTE: Iterative Workflow Tips:

Blow away only the local images (excluding remote ones) and bring down the container: $ docker-compose down --rmi local

Blow away all the images (including remote ones) and bring down the container: $ docker-compose down --rmi all