Merge pull request #5 from govlt/redoc-site

Generate ReDoc

.github/actions/prepare-python-environment/action.yml

@@ -0,0 +1,21 @@
+name: Prepare Python environment
+description: Setup python, poetry, SpatialLite and install dependencies
+
+runs:
+  using: composite
+  steps:
+    - name: Install poetry
+      uses: abatilo/actions-poetry@v2
+      with:
+        poetry-version: '1.8.*'
+
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: pyproject.toml
+        cache: poetry
+
+    - name: Install dependencies
+      run: poetry install --no-root
+      shell: bash
+

.github/workflows/ci.yml

@@ -27,6 +27,9 @@ jobs:
   validate-api-docker-build:
     name: Validate if docker image builds
     runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -37,3 +40,59 @@ jobs:
           environment: test
           file: Dockerfile
           push: false
+
+  generate-redoc:
+    name: Generate ReDoc
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Prepare environment
+        uses: ./.github/actions/prepare-python-environment
+
+      - name: Generate openapi.json
+        run: poetry run python src/extract-openapi.py src.main:app --out openapi.json
+
+      - name: Generate openapi.yaml
+        run: poetry run python src/extract-openapi.py src.main:app --out openapi.yaml
+
+      - name: Generate ReDoc html
+        run: npx @redocly/cli build-docs openapi.yaml
+
+      - name: Upload openapi.yaml artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi.yaml
+          path: openapi.yaml
+          if-no-files-found: error
+
+      - name: Upload openapi.json artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: openapi.json
+          path: openapi.json
+          if-no-files-found: error
+
+      - name: Upload redoc-static.html artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: redoc-static.html
+          path: redoc-static.html
+          if-no-files-found: error
+
+      - name: Create dist folder with files
+        run: |
+          mkdir dist
+          cp redoc-static.html dist/index.html
+          cp openapi.yaml openapi.json dist
+
+      - name: Upload to Cloudflare pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy dist --project-name=national-boundaries-api --commit-dirty=true

.gitignore

@@ -183,4 +183,8 @@ fabric.properties
 
 boundaries.sqlite
 mod_spatialite.dylib
-data-sources/
+data-sources/
+
+/openapi.json
+/openapi.yaml
+/redoc-static.html

src/extract-openapi.py

@@ -0,0 +1,33 @@
+# Adapted from https://www.doctave.com/blog/python-export-fastapi-openapi-spec
+
+import argparse
+import json
+import sys
+import yaml
+from uvicorn.importer import import_from_string
+
+parser = argparse.ArgumentParser(prog="extract-openapi.py")
+parser.add_argument("app", help='App import string. Eg. "src.main:app"', default="src.main:app")
+parser.add_argument("--app-dir", help="Directory containing the app", default=".")
+parser.add_argument("--out", help="Output file ending in .json or .yaml", default="openapi.yaml")
+
+if __name__ == "__main__":
+    args = parser.parse_args()
+
+    if args.app_dir is not None:
+        print(f"adding {args.app_dir} to sys.path")
+        sys.path.insert(0, args.app_dir)
+
+    print(f"importing app from {args.app}")
+    app = import_from_string(args.app)
+    openapi = app.openapi()
+    version = openapi.get("openapi", "unknown version")
+
+    print(f"writing openapi spec v{version}")
+    with open(args.out, "w") as f:
+        if args.out.endswith(".json"):
+            json.dump(openapi, f, indent=2)
+        else:
+            yaml.dump(openapi, f, sort_keys=False)
+
+    print(f"spec written to {args.out}")

src/main.py

@@ -31,18 +31,13 @@
                 '[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.lt). For more information, '
                 'visit [Registrų centras](https://www.registrucentras.lt/p/1187).',
     version="0.0.1",
-    terms_of_service="https://www.registrucentras.lt/p/1187",
+    terms_of_service="https://github.com/govlt/national-boundaries-api#license",
     docs_url="/",
     contact={
         "name": "Karolis Vyčius",
         "url": "https://vycius.lt/",
         "email": "karolis@vycius.lt",
-    },
-    license_info={
-        "name": "MIT for API and CC BY 4.0 for data",
-        "url": "https://github.com/govlt/national-boundaries-api#license",
-        "identifier": "CC-BY-4.0",
-    },
+    }
 )
 
 app.include_router(