This is an automated email from the ASF dual-hosted git repository.

mitchell852 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-trafficcontrol.git

commit 1245305051680727de02a30326d936092c84b428
Author: Dewayne Richardson <dewr...@apache.org>
AuthorDate: Wed Apr 18 09:00:38 2018 -0600

    updated to support swagger to rst conversion using Docker
    
    updated to point out the debug flag
    
    updated docs for docker-compose info
    
    updated the base url
    
    moved Dockerfile to top dir
    
    added swagger2rst.sh
    
    updated gitignore
    
    added files for swaggerspec to rst
---
 .../traffic_ops_golang/swaggerdocs/v13/.gitignore  |  3 +-
 .../swaggerdocs/v13/{docker => }/Dockerfile        |  1 +
 .../traffic_ops_golang/swaggerdocs/v13/README.md   | 42 ++++++++++++++++++----
 .../swaggerdocs/v13/docker-compose.yml             | 20 ++++++++++-
 .../traffic_ops_golang/swaggerdocs/v13/docs.go     |  2 +-
 .../swaggerdocs/v13/gen_swaggerspec.sh             |  3 +-
 .../v13/{docker => swaggerspec}/Dockerfile         | 18 +++++-----
 .../Dockerfile => swaggerspec/docker-compose.yml}  | 20 ++++++-----
 .../swaggerdocs/v13/swaggerspec/requirements.txt   |  1 +
 .../Dockerfile => swaggerspec/swagger2rst.sh}      | 17 ++++-----
 10 files changed, 90 insertions(+), 37 deletions(-)

diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/.gitignore 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/.gitignore
index 168aa94..3ccf628 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/.gitignore
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/.gitignore
@@ -1 +1,2 @@
-swagger.json
+swaggerspec/swagger.json
+swaggerspec/v13_api_docs.rst
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/Dockerfile
similarity index 99%
copy from traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
copy to traffic_ops/traffic_ops_golang/swaggerdocs/v13/Dockerfile
index fb3095f..4f6fd1f 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/Dockerfile
@@ -15,6 +15,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+ 
 FROM golang:1.10.1 AS go-swagger
 
 #  Swagger Spec Server
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
index 392e4e2..2153783 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
@@ -17,9 +17,9 @@
     under the License.
 -->
 
-#### `./swaggerdocs` 
-This directory contains the Go structs that glue together the Swagger 2.0 
metadata that will generate the Traffic Ops API documentation using 
[go-swagger](https://github.com/go-swagger/go-swagger) meta tags.  The Traffic 
Ops API documentation is maintained by modifying the Go files in this directory 
that point to the **incubator-trafficcontrol/lib/go-tc/*.go** structs that 
render the Traffic Ops Go Proxy API's.
+#### `./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](https://github.com/go-swagger/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 
**incubator-trafficcontrol/lib/go-tc/*.go**.  These combination of these two 
areas of .go files will produce Swagger documentation for the [...]
 
 ### Setup
 
@@ -29,18 +29,46 @@ This directory contains the Go structs that glue together 
the Swagger 2.0 metada
 * Install Docker Compose for your platform:
 
[https://docs.docker.com/compose/install](https://docs.docker.com/compose/install)
 
+### 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
 
-The `docker-compose.yml` will start 2 services a custom http service for 
hosting the `swaggerspec/swagger.json` and the Swagger UI.  
+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 just run:
+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](http://localhost:8080)
 
-### Generating your Swagger Spec File
+### Converting the swaggerspec/swagger.json to .rst
 
-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. 
+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```
 
-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.
\ No newline at end of file
+Blow away all the images (including remote ones) and bring down the container:
+```$ docker-compose down --rmi all```
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml
index 696438c..98a09ab 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml
@@ -1,10 +1,28 @@
+# 
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+
+#  http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+ 
 version: '3.6'
 
 services:
    swagger-spec-server:
      build:
        context: .
-       dockerfile: ./docker/Dockerfile
+       dockerfile: ./Dockerfile
      ports:
        - 8000:8000
      volumes:
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docs.go 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docs.go
index 730a8c7..11ecc71 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docs.go
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docs.go
@@ -6,7 +6,7 @@
  This documentation is fully compliant with the Swagger 2.0 specification
 
      Schemes: http, https
-        Host: localhost:8443
+        Host: your-traffic-ops
      BasePath: /api/1.3
      Version: 1.3
      License: Apache 2 
https://github.com/apache/incubator-trafficcontrol/blob/master/LICENSE
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh
index ce06d60..edeca44 100755
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh
@@ -17,8 +17,9 @@
 #    specific language governing permissions and limitations
 #    under the License.
 
-unset DEBUG
+# Uncomment (or set in your environment) to enable debug output for the 
swagger generation
 #export DEBUG=true
+
 OUTPUT_DIR=swaggerspec
 SWAGGER_SPEC_FILE=$OUTPUT_DIR/swagger.json
 mkdir -p $OUTPUT_DIR
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/Dockerfile
similarity index 75%
copy from traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
copy to traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/Dockerfile
index fb3095f..94b469b 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/Dockerfile
@@ -15,14 +15,16 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-FROM golang:1.10.1 AS go-swagger
+ 
+FROM python:2
 
-#  Swagger Spec Server
-FROM golang:1.10.1 AS swagger-server
+WORKDIR /usr/src/app
+RUN mkdir /swagger2rst
 
-ADD /swaggerspec .
-ADD ./swaggerspec-server /usr/src/swaggerspec-server
-WORKDIR /usr/src/swaggerspec-server
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
 
-RUN go build 
-ENTRYPOINT ["./swaggerspec-server"]
+ADD . .
+ADD swagger.json .
+
+CMD [ "./swagger2rst.sh" ]
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/docker-compose.yml
similarity index 75%
copy from traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
copy to 
traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/docker-compose.yml
index fb3095f..c461f96 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
+++ 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/docker-compose.yml
@@ -15,14 +15,18 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-FROM golang:1.10.1 AS go-swagger
+ 
+version: '3.6'
 
-#  Swagger Spec Server
-FROM golang:1.10.1 AS swagger-server
+services:
+   to-rst:
+     build:
+       context: .
+       dockerfile: ./Dockerfile
+     volumes:
+       - .:/swagger2rst
 
-ADD /swaggerspec .
-ADD ./swaggerspec-server /usr/src/swaggerspec-server
-WORKDIR /usr/src/swaggerspec-server
 
-RUN go build 
-ENTRYPOINT ["./swaggerspec-server"]
+volumes:
+    swagger2rst:
+
diff --git 
a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/requirements.txt 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/requirements.txt
new file mode 100644
index 0000000..96c9e84
--- /dev/null
+++ 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/requirements.txt
@@ -0,0 +1 @@
+swagger2rst
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile 
b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/swagger2rst.sh
old mode 100644
new mode 100755
similarity index 75%
rename from traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
rename to 
traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/swagger2rst.sh
index fb3095f..ae59737
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/swagger2rst.sh
@@ -1,3 +1,5 @@
+#!/usr/bin/env bash
+
 # 
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
@@ -15,14 +17,9 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-FROM golang:1.10.1 AS go-swagger
-
-#  Swagger Spec Server
-FROM golang:1.10.1 AS swagger-server
-
-ADD /swaggerspec .
-ADD ./swaggerspec-server /usr/src/swaggerspec-server
-WORKDIR /usr/src/swaggerspec-server
 
-RUN go build 
-ENTRYPOINT ["./swaggerspec-server"]
+OUTPUT_DIR=/swagger2rst
+OUTPUT_FILE=v13_api_docs.rst
+RST_FILE=$OUTPUT_DIR/$OUTPUT_FILE
+swg2rst swagger.json -f rst -o $RST_FILE
+echo "Created $OUTPUT_FILE from swagger.json"

-- 
To stop receiving notification emails like this one, please contact
mitchell...@apache.org.

Reply via email to