You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficcontrol.apache.org by mi...@apache.org on 2018/04/18 20:50:41 UTC
[incubator-trafficcontrol] 05/05: updated to support swagger to rst
conversion using Docker
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 <de...@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
mitchell852@apache.org.