Skip to content
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

Referenced yml files are not copied #38

Open
guoquan opened this issue Aug 6, 2021 · 2 comments
Open

Referenced yml files are not copied #38

guoquan opened this issue Aug 6, 2021 · 2 comments

Comments

@guoquan
Copy link

guoquan commented Aug 6, 2021

My (local) yml spec file references to another (local) yml in the definition. However, the extension seems not able to detect the reference and copy them.
For example:

a.yml

# ...
components:
  schemas:
    user:
      $ref: 'b.yml#/components/schemas/user'
# ...

b.yml

# ...
components:
  schemas:
    user:
      type: object
# ...

and in conf.py

# ...
redoc = [
    {
        "name": "My API",
        "page": "path/to/a",
        "spec": "path/to/a.yml",
    },
]
# ...

The extension detects "path/to/a.yml" and copy it to _build/html/_spec. However, b.yml is not copied and the page just failed to load.

Could there be a way to list the yml files I want to use for rendering the docs page, and the extension will copy and prepare them (and manipulate the paths) for me?

@guoquan
Copy link
Author

guoquan commented Aug 6, 2021

With tools like https://github.com/wework/speccy we can allow a list of spec and merge them into one so that the current process is good.

@guoquan
Copy link
Author

guoquan commented Aug 7, 2021

If anyone is interested, I came up with a workaround merging the files at the build time in conf.py with prance.
(speccy ran into an infinite loop with my spec file)

However, it would be good if supported in the extension.

# conf.py

def resolve(path: str, to: str = None):
    import logging
    import subprocess
    import tempfile
    from os.path import basename, join

    if to is None:
        basenames = basename(path).rsplit(".", maxsplit=2)
        assert len(basenames) == 2
        # to = to or f"{path_names[0]}.resolved.{path_names[1]}"
        to = f"{join(tempfile.gettempdir(),basenames[0])}.resolved.{basenames[1]}"

    subprocess.run(["prance", "compile", path, to])
    logging.getLogger(__name__).info(f"Resolved {path} to {to}")

    return to

redoc = [
    {
        "name": "My API",
        "page": "my/api/index",
        "spec": resolve("my/api/index.yml"),
        "embed": True,
    },
]

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