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:38 UTC
[incubator-trafficcontrol] 02/05: converted the swaggerdocs
generation into a Docker infrastructure
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 ac22015279564a6c231fa531fb254e12fc47b251
Author: Dewayne Richardson <de...@apache.org>
AuthorDate: Tue Apr 17 10:29:30 2018 -0600
converted the swaggerdocs generation into a Docker infrastructure
---
.../traffic_ops_golang/swaggerdocs/v13/README.md | 34 ++++++++++------------
.../swaggerdocs/v13/docker-compose.yml | 15 +++++++---
.../swaggerdocs/v13/docker/Dockerfile | 28 ++++--------------
.../v13/{gen_docs.sh => gen_swaggerspec.sh} | 7 +++--
.../swaggerdocs/v13/swagger-server/Dockerfile | 29 ------------------
.../swaggerspec-server.go} | 8 +++--
6 files changed, 42 insertions(+), 79 deletions(-)
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
index 19fff3d..f92bbbd 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md
@@ -23,32 +23,28 @@ This directory contains the Go structs that glue together the Swagger 2.0 metada
### Setup
-See the install documentation for [https://github.com/go-swagger/go-swagger](go-swagger)
+* Install Docker for your platform:
+[https://docs.docker.com/install](https://docs.docker.com/install)
+* Install Docker Compose for your platform:
+[https://docs.docker.com/compose/install](https://docs.docker.com/compose/install)
-### Generate your Documentation
+### Running
-The **gen_docs.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_docs.sh** script will be the **swagger.json** spec file.
+The docker-compose.yml will start 2 services a custom http service for hosting the `swaggerspec/swagger.json` and the Swagger UI.
-### Verifying your Documentation
+To start the Swagger UI services just run:
-Once the **swagger.json** spec file has been generated it needs to to be served over http so that you can validate it using the Swagger Editor.
+```$ docker-compose up```
-See the following steps:
+Once started navigate your browser to [http://localhost:8080](http://localhost:8080)
-* Execute the **cors-http-server.py** (this will start a server on **http://localhost:8000**
- so that you can point to it using the [https://editor.swagger.io](Swagger Editor).
-
- `$ ./cors-http-server.py`
+### Generating your Swagger Spec File
-* Navigate to [https://editor.swagger.io](Swagger Editor)
-
-* Use File->Import URL then plugin **http://localhost:8000**
- * At this point the Swagger Editor will convert the **swagger.json** to yaml format and show the resulting documentation rendered as html.
+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.
- OR
-
-* Install the [https://swagger.io/swagger-ui/](Swagger UI) yourself and run locally.
-
-
+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.
+### Verifying your Documentation
+
+Once the **swagger.json** spec file has been generated it needs to to be served over http so that you can validate it using the Swagger Editor.
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 ad92633..696438c 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml
@@ -1,15 +1,22 @@
version: '3.6'
-
+
services:
- swagger-generator:
+ swagger-spec-server:
build:
context: .
dockerfile: ./docker/Dockerfile
ports:
- 8000:8000
volumes:
- - output:/output
+ - ./swaggerspec:/swaggerspec
+
+ swagger-ui:
+ image: swaggerapi/swagger-ui
+ ports:
+ - 8080:8080
+ environment:
+ - API_URL=http://localhost:8000/swaggerspec/swagger.json
volumes:
- output:
+ swaggerspec:
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
index e89ae50..fb3095f 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker/Dockerfile
@@ -15,30 +15,14 @@
# 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 golang:1.10.1 AS swagger-gen
-
-RUN mkdir /go/src/v13
-WORKDIR /go/src/v13
-ADD . .
-
-RUN mkdir /output
-
-RUN go get -d -v ./...
-RUN go install -v ./...
-RUN go get -u github.com/go-swagger/go-swagger/cmd/swagger
-
-CMD ["./gen_docs.sh"]
-
+# Swagger Spec Server
FROM golang:1.10.1 AS swagger-server
-#RUN mkdir /usr/src/swagger-server
-
-ADD ./swagger-server /usr/src/swagger-server
-WORKDIR /usr/src/swagger-server
-
-
-COPY --from=swagger-gen /output /output
+ADD /swaggerspec .
+ADD ./swaggerspec-server /usr/src/swaggerspec-server
+WORKDIR /usr/src/swaggerspec-server
RUN go build
-CMD ["./swagger-server"]
+ENTRYPOINT ["./swaggerspec-server"]
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_docs.sh b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh
similarity index 81%
rename from traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_docs.sh
rename to traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh
index 02ccec2..ce06d60 100755
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_docs.sh
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh
@@ -19,5 +19,8 @@
unset DEBUG
#export DEBUG=true
-swagger generate spec -o /output/swagger.json
-echo "successfully generated swagger output file: ./swagger.json"
+OUTPUT_DIR=swaggerspec
+SWAGGER_SPEC_FILE=$OUTPUT_DIR/swagger.json
+mkdir -p $OUTPUT_DIR
+swagger generate spec -o $SWAGGER_SPEC_FILE
+echo "successfully generated swagger output file: $SWAGGER_SPEC_FILE"
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swagger-server/Dockerfile b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swagger-server/Dockerfile
deleted file mode 100644
index 8deba91..0000000
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swagger-server/Dockerfile
+++ /dev/null
@@ -1,29 +0,0 @@
-#
-# 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.
-
-FROM golang:1.10.1 AS swagger-server
-
-WORKDIR /usr/src/app
-COPY /output/swagger.json .
-
-ADD . .
-RUN go build
-
-COPY --from=swagger-gen /output /output
-
-CMD ["./app"]
diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swagger-server/swagger-server.go b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec-server/swaggerspec-server.go
similarity index 60%
rename from traffic_ops/traffic_ops_golang/swaggerdocs/v13/swagger-server/swagger-server.go
rename to traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec-server/swaggerspec-server.go
index a873ad7..6d27c1b 100644
--- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swagger-server/swagger-server.go
+++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec-server/swaggerspec-server.go
@@ -7,18 +7,20 @@ import (
)
func main() {
+ hostName := flag.String("h", "localhost", "hostname to serve on")
port := flag.String("p", "8000", "port to serve on")
flag.Parse()
- swaggerFile := "swagger.json"
+ swaggerFile := "/swaggerspec/swagger.json"
- http.HandleFunc("/swagger.json", func(w http.ResponseWriter, r *http.Request) {
+ http.HandleFunc(swaggerFile, func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Credentials", "true")
w.Header().Set("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie")
w.Header().Set("Access-Control-Allow-Methods", "POST,GET,OPTIONS,PUT,DELETE")
w.Header().Set("Access-Control-Allow-Origin", "*")
http.ServeFile(w, r, swaggerFile)
})
- log.Printf("Serving %s on HTTP port: %s\n", swaggerFile, *port)
+ log.Printf("Serving swagger spec file here: http://%s:%s%s\n", *hostName, *port, swaggerFile)
+ log.Printf("Serving Swagger UI here: http://localhost:8080\n")
log.Fatal(http.ListenAndServe(":"+*port, nil))
}
--
To stop receiving notification emails like this one, please contact
mitchell852@apache.org.