change openapi/docs url and update landing page (#671)

* change openapi/docs url and update landing page

* update tests

CHANGES.md

@@ -1,5 +1,12 @@
 # Release Notes
 
+## Unreleased
+
+### titiler.application
+
+* use `/api` and `/api.html` for documentation (instead of `/openapi.json` and `/docs`)
+* update landing page
+
 ## 0.12.0 (2023-07-17)
 
 * use `Annotated` Type for Query/Path parameters

src/titiler/application/tests/test_main.py

@@ -7,8 +7,8 @@ def test_health(app):
     assert response.status_code == 200
     assert response.json() == {"ping": "pong!"}
 
-    response = app.get("/openapi.json")
+    response = app.get("/api")
     assert response.status_code == 200
 
-    response = app.get("/docs")
+    response = app.get("/api.html")
     assert response.status_code == 200

src/titiler/application/titiler/application/main.py

@@ -49,6 +49,8 @@
 
 app = FastAPI(
     title=api_settings.name,
+    openapi_url="/api",
+    docs_url="/api.html",
     description="""A modern dynamic tile server built on top of FastAPI and Rasterio/GDAL.
 
 ---
@@ -162,9 +164,70 @@ def ping():
 
 @app.get("/", response_class=HTMLResponse, include_in_schema=False)
 def landing(request: Request):
-    """TiTiler Landing page"""
+    """TiTiler landing page."""
+    data = {
+        "title": "titiler",
+        "links": [
+            {
+                "title": "Landing page",
+                "href": str(request.url_for("landing")),
+                "type": "text/html",
+                "rel": "self",
+            },
+            {
+                "title": "the API definition (JSON)",
+                "href": str(request.url_for("openapi")),
+                "type": "application/vnd.oai.openapi+json;version=3.0",
+                "rel": "service-desc",
+            },
+            {
+                "title": "the API documentation",
+                "href": str(request.url_for("swagger_ui_html")),
+                "type": "text/html",
+                "rel": "service-doc",
+            },
+            {
+                "title": "TiTiler Documentation (external link)",
+                "href": "https://developmentseed.org/titiler/",
+                "type": "text/html",
+                "rel": "doc",
+            },
+            {
+                "title": "TiTiler source code (external link)",
+                "href": "https://github.com/developmentseed/titiler",
+                "type": "text/html",
+                "rel": "doc",
+            },
+        ],
+    }
+
+    urlpath = request.url.path
+    crumbs = []
+    baseurl = str(request.base_url).rstrip("/")
+
+    crumbpath = str(baseurl)
+    for crumb in urlpath.split("/"):
+        crumbpath = crumbpath.rstrip("/")
+        part = crumb
+        if part is None or part == "":
+            part = "Home"
+        crumbpath += f"/{crumb}"
+        crumbs.append({"url": crumbpath.rstrip("/"), "part": part.capitalize()})
+
     return templates.TemplateResponse(
-        name="index.html",
-        context={"request": request},
-        media_type="text/html",
+        "index.html",
+        {
+            "request": request,
+            "response": data,
+            "template": {
+                "api_root": baseurl,
+                "params": request.query_params,
+                "title": "TiTiler",
+            },
+            "crumbs": crumbs,
+            "url": str(request.url),
+            "baseurl": baseurl,
+            "urlpath": str(request.url.path),
+            "urlparams": str(request.url.query),
+        },
     )