mitchell852 closed pull request #2143: Improved the Swagger Doc generation with Docker URL: https://github.com/apache/incubator-trafficcontrol/pull/2143
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/.gitignore b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/.gitignore index 168aa9434..3ccf628e6 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/Dockerfile b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/Dockerfile new file mode 100644 index 000000000..4f6fd1f3b --- /dev/null +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/Dockerfile @@ -0,0 +1,29 @@ +# +# 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 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"] diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md index 19fff3da1..215378351 100644 --- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/README.md @@ -17,38 +17,58 @@ 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 Traffic Ops Go API's. ### 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 +### Generating your Swagger Spec File -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 **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. -### Verifying your Documentation +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. -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. +### Running the web services -See the following steps: +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. -* 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` +The `docker-compose.yml` will start two rendering services, a custom http service for hosting the `swaggerspec/swagger.json` and the Swagger UI. -* 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. +To start the Swagger UI services (and build them if not already built) just run: - OR - -* Install the [https://swagger.io/swagger-ui/](Swagger UI) yourself and run locally. - - +```$ 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) + +### 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``` diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/cors-http-server.py b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/cors-http-server.py deleted file mode 100755 index 3c1687f87..000000000 --- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/cors-http-server.py +++ /dev/null @@ -1,33 +0,0 @@ -#!/usr/bin/env python - - - # 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 SimpleHTTPServer import SimpleHTTPRequestHandler -import BaseHTTPServer - -# -# Simple HTTP server that serves up port 8000 with the CORS header enabled -# -class CORSRequestHandler (SimpleHTTPRequestHandler): - def end_headers (self): - self.send_header('Access-Control-Allow-Origin', '*') - SimpleHTTPRequestHandler.end_headers(self) - -if __name__ == '__main__': - BaseHTTPServer.test(CORSRequestHandler, BaseHTTPServer.HTTPServer) diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml new file mode 100644 index 000000000..98a09ab1b --- /dev/null +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docker-compose.yml @@ -0,0 +1,40 @@ +# +# 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: ./Dockerfile + ports: + - 8000:8000 + volumes: + - ./swaggerspec:/swaggerspec + + swagger-ui: + image: swaggerapi/swagger-ui + ports: + - 8080:8080 + environment: + - API_URL=http://localhost:8000/swaggerspec/swagger.json + +volumes: + swaggerspec: + diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docs.go b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/docs.go index 730a8c752..11ecc7194 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_docs.sh b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh similarity index 74% 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 a7c715428..edeca44e9 100755 --- a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_docs.sh +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/gen_swaggerspec.sh @@ -17,7 +17,11 @@ # 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 -swagger generate spec -o ./swagger.json -echo "successfully generated the swagger.json file" + +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/swaggerspec-server/swaggerspec-server.go b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec-server/swaggerspec-server.go new file mode 100644 index 000000000..6d27c1b0c --- /dev/null +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec-server/swaggerspec-server.go @@ -0,0 +1,26 @@ +package main + +import ( + "flag" + "log" + "net/http" +) + +func main() { + hostName := flag.String("h", "localhost", "hostname to serve on") + port := flag.String("p", "8000", "port to serve on") + flag.Parse() + + swaggerFile := "/swaggerspec/swagger.json" + + 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 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)) +} diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/Dockerfile b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/Dockerfile new file mode 100644 index 000000000..94b469b98 --- /dev/null +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/Dockerfile @@ -0,0 +1,30 @@ +# +# 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 python:2 + +WORKDIR /usr/src/app +RUN mkdir /swagger2rst + +COPY requirements.txt ./ +RUN pip install --no-cache-dir -r requirements.txt + +ADD . . +ADD swagger.json . + +CMD [ "./swagger2rst.sh" ] diff --git a/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/docker-compose.yml b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/docker-compose.yml new file mode 100644 index 000000000..c461f968b --- /dev/null +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/docker-compose.yml @@ -0,0 +1,32 @@ +# +# 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: + to-rst: + build: + context: . + dockerfile: ./Dockerfile + volumes: + - .:/swagger2rst + + +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 000000000..96c9e84f9 --- /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/swaggerspec/swagger2rst.sh b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/swagger2rst.sh new file mode 100755 index 000000000..ae59737bf --- /dev/null +++ b/traffic_ops/traffic_ops_golang/swaggerdocs/v13/swaggerspec/swagger2rst.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash + +# +# 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. + +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" ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
