Skip to content

Allow localhost openapi files #617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
richloh opened this issue Apr 8, 2025 · 0 comments
Open

Allow localhost openapi files #617

richloh opened this issue Apr 8, 2025 · 0 comments

Comments

@richloh
Copy link

richloh commented Apr 8, 2025

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant