erabo/spiegel_podman
1
0
Fork 0
mirror of https://github.com/podman-container-tools/podman.git synced 2026-08-05 00:15:44 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

docs: update API Reference docs

Browse source 
I forgot to update the docs here when I reworked the build process. Link
to the new location and explain how users can download the file, see
https://github.com/podman-container-tools/podman/discussions/29035

Now because the file is served on the same domain there should also be
no longer any issue with CORS so remove the old picture.

Fixes: c2ffe88ce0 ("build the swagger.yml on readthedocs")

Signed-off-by: Paul Holzinger <pholzing@redhat.com>
This commit is contained in:
Paul Holzinger 2026-06-25 14:47:25 +02:00
parent fef6af086a
commit 8136cfbe4d
No known key found for this signature in database
GPG key ID: EB145DD938A3CAF2
2 changed files with 9 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
docs/README.md
View file

@ -33,29 +33,16 @@ The syntax for the formatting of all man pages can be found [here](MANPAGE_SYNTA
## API Reference ## API Reference
The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is The [latest online documentation](https://docs.podman.io/en/latest/_static/api.html) is
automatically generated by two cooperating automation systems based on committed upstream automatically generated by the readthedocs build process. It uses redoc to render the
source code. Firstly, the [`Publish swagger` GitHub Actions workflow](../.github/workflows/swagger.yml) swagger.yml file, the swagger is build and injected as static resource in the readthedocs
builds `pkg/api/swagger.yaml` and uploads it to a public-facing location (Google Storage Bucket - build process, see the [`.readthedocs.yaml`](../.readthedocs.yaml) file.
an online service for storing unstructured data). Second, [Read The Docs](readthedocs.com)
reacts to the github.com repository change, building the content for the [libpod documentation
site](https://podman.readthedocs.io/). This site includes for the API section,
some javascript which consumes the uploaded `swagger.yaml` file directly from the Google
Storage Bucket.
Since there are multiple systems and local cache is involved, it's possible that updates to The swagger file can be downloaded from `https://docs.podman.io/en/latest/_static/swagger.yaml`.
documentation (especially the swagger/API docs) will lag by 10-or-so minutes. However, Note the latest link always contains the latest yaml from the main branch, if you like a specific
because the client (i.e. your web browser) is fetching content from multiple locations that version replace `latest` with the version, i.e. for `v6.0.0` `https://docs.podman.io/en/v6.0.0/_static/swagger.yaml`.
do not share a common domain, accessing the API section may show a stack-trace similar to Also this new process is only done since v5.8.4. Earlier swagger.yml files where
the following: uploaded [here](https://storage.googleapis.com/libpod-master-releases).
![JavaScript Stack Trace Image](../hack/ci/swagger_stack_trace.png)
If reloading the page, or clearing your local cache does not fix the problem, it is
likely caused by broken metadata needed to protect clients from cross-site-scripting
style attacks. Please [notify a maintainer](https://github.com/containers/podman#communications)
so they may investigate how/why the `swagger.yaml` file's CORS-metadata is
incorrect, or the file isn't accessible for some other reason.
## Local Testing ## Local Testing

BIN
hack/ci/swagger_stack_trace.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 42 KiB