Categorygithub.com/apache/incubator-trafficcontroltraffic_opstraffic_ops_golangswaggerdocsv13
package
7.0.1+incompatible
Repository: https://github.com/apache/incubator-trafficcontrol.git
Documentation: pkg.go.dev
Overview
Versions
3
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.