Categorygithub.com/apache/trafficcontrol/v8traffic_opstraffic_ops_golangswaggerdocsv13
package
8.0.2
Repository: https://github.com/apache/trafficcontrol.git
Documentation: pkg.go.dev
Overview
Versions
4
Dependencies
1
Dependents
0
Files
552 SLOC

# README

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

# Packages

No description provided by the author

# Functions

DeleteASN swagger:route DELETE /asns/{id} ASN DeleteASN # Delete an ASN by Id # Delete an ASN Responses: 200: Alerts.
DeleteCDN swagger:route DELETE /cdns/{id} CDN DeleteCDN # Delete a CDN by Id # Delete a CDN Responses: 200: Alerts.
DeleteDivision swagger:route DELETE /divisions/{id} Division DeleteDivision # Delete a Division by Id # Delete a single Division Responses: 200: Alerts.
DeletePhysLocation swagger:route DELETE /phys_locations/{id} PhysLocation DeletePhysLocation # Delete a PhysLocation by Id # Delete a PhysLocation Responses: 200: Alerts.
DeleteProfile swagger:route DELETE /cdns/{id} Profile DeleteProfile # Delete a Profile by Id # Delete a Profile Responses: 200: Alerts.
DeleteProfileParameter swagger:route DELETE /profileparameters/{id} ProfileParameter DeleteProfileParameter # Delete a ProfileParameter by Id # Delete a single ProfileParameter Responses: 200: Alerts.
DeleteRegion swagger:route DELETE /regions/{id} Region DeleteRegion # Delete a Region Responses: 200: Alerts.
DeleteStatus swagger:route DELETE /statuses/{id} Status DeleteStatus # Delete a Status Responses: 200: Alerts.
GetASNById swagger:route GET /asns/{id} ASN GetASNById # Retrieve a specific ASN by Id # Retrieve an ASN Responses: 200: ASNs 400: Alerts.
GetASNs swagger:route GET /asns ASN GetASNs # Retrieve a list of ASNs # A list of ASNs Responses: 200: ASNs 400: Alerts.
GetCDNById swagger:route GET /cdns/{id} CDN GetCDNById # Retrieve a specific CDN by Id # Retrieve a specific CDN Responses: 200: CDNs 400: Alerts.
GetCDNs swagger:route GET /cdns CDN GetCDNs # Retrieve a list of CDNs # List of CDNs Responses: 200: CDNs 400: Alerts.
GetDivisionById swagger:route GET /divisions/{id} Division GetDivisionById # Retrieve a specific Division by Id # Retrieve a single division Responses: 200: Divisions 400: Alerts.
GetDivisions swagger:route GET /divisions Division GetDivisions # Retrieve a list of Divisions # List of Divisions Responses: 200: Divisions 400: Alerts.
GetPhysLocationById swagger:route GET /phys_locations/{id} PhysLocation GetPhysLocationById # Retrieve a specific PhysLocation by Id # Retrieve a specific PhysLocation Responses: 200: PhysLocations 400: Alerts.
GetPhysLocations swagger:route GET /phys_locations PhysLocation GetPhysLocations # Retrieve a list of PhysLocations # List of PhysLocations Responses: 200: PhysLocations 400: Alerts.
GetProfileById swagger:route GET /cdns/{id} Profile GetProfileById # Retrieve a specific Profile by Id # Retrieve a specific Profile Responses: 200: Profiles 400: Alerts.
GetProfileParameterById swagger:route GET /profileparameters?id={id} ProfileParameter GetProfileParameterById # Retrieve a specific ProfileParameter by Id # Retrieve a single division Responses: 200: ProfileParameters 400: Alerts.
GetProfileParameters swagger:route GET /profileparameters ProfileParameter GetProfileParameters # Retrieve a list of ProfileParameters by narrowing down with query parameters # List of ProfileParameters Responses: 200: ProfileParameters 400: Alerts.
GetProfiles swagger:route GET /cdns Profile GetProfiles # Retrieve a list of Profiles # List of Profiles Responses: 200: Profiles 400: Alerts.
GetRegionById swagger:route GET /regions/{id} Region GetRegionById # Retrieve a specific Region Responses: 200: Regions 400: Alerts.
GetRegions swagger:route GET /regions Region GetRegions # Retrieve a list of Regions Responses: 200: Regions 400: Alerts.
GetStatusById swagger:route GET /statuses/{id} Status GetStatusById # Retrieve a specific Status Responses: 200: Statuses 400: Alerts.
GetStatuses swagger:route GET /statuses Status GetStatuses # Retrieve a list of Statuses Responses: 200: Statuses 400: Alerts.
PostASN swagger:route POST /asns ASN PostASN # Create a ASN # An Autonomous System Number Responses: 200: Alerts.
PostCDN swagger:route POST /cdns CDN PostCDN # Create a CDN # A CDN is a collection of Delivery Services Responses: 200: Alerts.
PostDivision swagger:route POST /divisions Division PostDivision # Create a Division # A Division is a group of regions Responses: 200: Alerts.
PostPhysLocation swagger:route POST /phys_locations PhysLocation PostPhysLocation # Create a PhysLocation # A PhysLocation is a collection of Delivery Services Responses: 200: Alerts.
PostProfile swagger:route POST /cdns Profile PostProfile # Create a Profile # A Profile is a collection of Delivery Services Responses: 200: Alerts.
PostProfileParameter swagger:route POST /profileparameters ProfileParameter PostProfileParameter # Create a ProfileParameter # A ProfileParameter is a join of the Profile and Parameters Responses: 200: Alerts.
PostRegion swagger:route POST /regions Region PostRegion # Create a Region Responses: 200: Alerts.
PostStatus swagger:route POST /statuses Status PostStatus # Create a Status Responses: 200: Alerts.
PutASN swagger:route PUT /asns/{id} ASN PutASN # Update an ASN by Id # Update an ASN Responses: 200: ASN.
PutCDN swagger:route PUT /cdns/{id} CDN PutCDN # Update a CDN by Id # Update a CDN Responses: 200: CDN.
PutDivision swagger:route PUT /divisions/{id} Division PutDivision # Update a Division by Id # Update a single Division Responses: 200: Division.
PutPhysLocation swagger:route PUT /phys_locations/{id} PhysLocation PutPhysLocation # Update a PhysLocation by Id # Update a PhysLocation Responses: 200: PhysLocation.
PutProfile swagger:route PUT /cdns/{id} Profile PutProfile # Update a Profile by Id # Update a Profile Responses: 200: Profile.
PutRegion swagger:route PUT /regions/{id} Region PutRegion # Update a Region Responses: 200: Region.
PutStatus swagger:route PUT /statuses/{id} Status PutStatus # Update a Status Responses: 200: Status.

# Structs

Alerts - informs the client of server side messages swagger:response Alerts.
ASN - ASNResponse to get the "response" top level key swagger:response ASN in: body.
swagger:parameters GetASNById DeleteASN.
swagger:parameters PostASN.
swagger:parameters PutASN.
ASNQueryParams swagger:parameters GetASNs.
ASNs - ASNsResponse to get the "response" top level key swagger:response ASNs in: body.
CDN - CDNResponse to get the "response" top level key swagger:response CDN in: body.
swagger:parameters GetCDNById DeleteCDN.
swagger:parameters PostCDN.
swagger:parameters PutCDN.
CDNQueryParams swagger:parameters GetCDNs.
CDNs - CDNsResponse to get the "response" top level key swagger:response CDNs in: body.
Division - DivisionResponse to get the "response" top level key swagger:response Division in: body.
swagger:parameters GetDivisionById DeleteDivision.
swagger:parameters PostDivision.
swagger:parameters PutDivision.
DivisionQueryParams swagger:parameters GetDivisions.
Divisions - DivisionsResponse to get the "response" top level key swagger:response Divisions in: body.
PhysLocation - PhysLocationResponse to get the "response" top level key swagger:response PhysLocation in: body.
swagger:parameters GetPhysLocationById DeletePhysLocation.
swagger:parameters PostPhysLocation.
swagger:parameters PutPhysLocation.
PhysLocationQueryParams swagger:parameters GetPhysLocations.
PhysLocations - PhysLocationsResponse to get the "response" top level key swagger:response PhysLocations in: body.
Profile - ProfileResponse to get the "response" top level key swagger:response Profile in: body.
ProfileParameter - ProfileParameterResponse to get the "response" top level key swagger:response ProfileParameter in: body.
swagger:parameters PostProfileParameter.
ProfileParameterQueryParams swagger:parameters GetProfileParameters.
ProfileParameters - ProfileParametersResponse to get the "response" top level key swagger:response ProfileParameters in: body.
swagger:parameters GetProfileById DeleteProfile.
swagger:parameters PostProfile.
swagger:parameters PutProfile.
ProfileQueryParams swagger:parameters GetProfiles.
Profiles - ProfilesResponse to get the "response" top level key swagger:response Profiles in: body.
Region - RegionResponse to get the "response" top level key swagger:response Region in: body.
swagger:parameters GetRegionById DeleteRegion.
swagger:parameters PostRegion.
swagger:parameters PutRegion.
RegionQueryParams swagger:parameters GetRegions.
Regions - RegionsResponse to get the "response" top level key swagger:response Regions in: body.
Status - StatusResponse to get the "response" top level key swagger:response Status in: body.
Statuses - StatusesResponse to get the "response" top level key swagger:response Statuses in: body.
swagger:parameters GetStatusById DeleteStatus.
swagger:parameters PostStatus.
swagger:parameters PutStatus.
StatusQueryParams swagger:parameters GetStatuses.