docs

docs copied to clipboard

Currently, Mintlify works well with OpenAPI documentation files on external web servers, as in this example docs.json:

{
  "$schema": "https://mintlify.com/docs.json",
  "navigation": {
    "languages": [
      {
        "anchors": [
          {
            "anchor": "API Dokumentation",
            "openapi": {
              "source": "https://my-server.com/api/mind/docs/open-api",
              "directory": "de/api-reference"
            },
            [...]

However, mintlify is extremely strict on syntax. So even if a regular OpenAPI UI renders, that does not mean that Mintlify will render. That in itself is not a problem. However, local debugging and finding the issue is tedious, as it is impossible to reference to a local openapi file from a local server. This is the case if a web service compiles the open api file from various sources.

Example:

docs.json:

{
            "openapi": {
              "source": "http://localhost:8000/api/mind/docs/open-api",
              "directory": "de/api-reference"
            },
            [...]

Results in

richard@BerlinPC ~/e/docs (main)> mintlify dev
⠋ Preparing local Mintlify instance...🚨 Invalid docs.json:
#.navigation.languages[0].anchors[1].openapi.source: Must use protocol https
✖ Prebuild step failed

Suggested solutions

• Allow localhost urls (http://localhost and http://127.0.0.1) as valid http-sources for openapi files