github-starred/ollama
2
0
Fork 0
mirror of https://github.com/ollama/ollama.git synced 2026-05-07 00:22:43 -05:00
Code Issues 14.5k Packages Projects Releases 120 Wiki Activity

[GH-ISSUE #3383] Provide an updated OpenAPI Specification file (a/k/a "swagger file") with each release #48590

New Issue
Open
opened 2026-04-28 08:55:34 -05:00 by GiteaMirror · 5 comments
GiteaMirror commented 2026-04-28 08:55:34 -05:00
Owner
Copy Link

Originally created by @jimscard on GitHub (Mar 28, 2024).
Original GitHub issue: https://github.com/ollama/ollama/issues/3383

What are you trying to do?

Development and debugging of applications that call APIs require the use of tools to call the APIs to simulate actions that the applications would take. Some of these tools include Postman and (arguably the best one now) Bruno. Additionally, API security testing tools, such as OWASP OFFAT, need to be able to call the APIs and exercise all of their functions in order to detect security bugs/vulnerabilities.
There is a standard for the developers of APIs, such as the Ollama maintainers, to document their APIs in a machine-readable format that is understood by these tools. Ollama needs to provide such a description of the Ollama API, updated each time it changes. The standard format is the OpenAPI Specification, maintained by the OpenAPI Initiative, under the Linux Foundation. Details can be found at: https://www.openapis.org/
Note: This was originally developed by a company called "Swagger", and later donated to the OpenAPI Initiative. Hence, files containing an OpenAPI description are sometimes referred to as "Swagger files".

How should we solve this?

Fully document the ollama API in an OpenAPI format file, published and maintained as part of the ollama distribution in this repository.

What is the impact of not solving this?

It's necessary to either handcraft every request to the API, or build an OpenAPI format file to use with the tools. Some examples of these files crafted by people outside of the project exist, however, they at best represent the state of the API at the time that the file was made, and at worst, are both out of date, and inaccurate. It is the inaccuracy that is most concerning, since missing/incompletely described APIs inhibit the ability of security testing tools to test the entire attack surface presented by the API.
An examination of the help messages on Discord, and the issues posted here in Github, show that Ollama's popularity as the backend of applications used by multiple people, across networks or the Internet, underscores the importance of making security testing as friction-free as possible, and a complete, maintained OpenAPI file is a key part of that.

Anything else?

OpenAPI spec for OpenAI api -- https://github.com/openai/openai-openapi
OpenAPI Specification -- https://github.com/OAI/OpenAPI-Specification
A third party OpenAPI spec file for Ollama (last updated 2024-02-02; accuracy unknown) -- https://github.com/davidmigloz/langchain_dart/blob/main/packages/ollama_dart/oas/ollama-curated.yaml

Originally created by @jimscard on GitHub (Mar 28, 2024). Original GitHub issue: https://github.com/ollama/ollama/issues/3383 ### What are you trying to do? Development and debugging of applications that call APIs require the use of tools to call the APIs to simulate actions that the applications would take. Some of these tools include Postman and (arguably the best one now) Bruno. Additionally, API security testing tools, such as OWASP OFFAT, need to be able to call the APIs and exercise all of their functions in order to detect security bugs/vulnerabilities. There is a standard for the developers of APIs, such as the Ollama maintainers, to document their APIs in a machine-readable format that is understood by these tools. Ollama needs to provide such a description of the Ollama API, updated each time it changes. The standard format is the OpenAPI Specification, maintained by the OpenAPI Initiative, under the Linux Foundation. Details can be found at: https://www.openapis.org/ Note: This was originally developed by a company called "Swagger", and later donated to the OpenAPI Initiative. Hence, files containing an OpenAPI description are sometimes referred to as "Swagger files". ### How should we solve this? Fully document the ollama API in an OpenAPI format file, published and maintained as part of the ollama distribution in this repository. ### What is the impact of not solving this? It's necessary to either handcraft every request to the API, or build an OpenAPI format file to use with the tools. Some examples of these files crafted by people outside of the project exist, however, they at best represent the state of the API at the time that the file was made, and at worst, are both out of date, and inaccurate. It is the inaccuracy that is most concerning, since missing/incompletely described APIs inhibit the ability of security testing tools to test the entire attack surface presented by the API. An examination of the help messages on Discord, and the issues posted here in Github, show that Ollama's popularity as the backend of applications used by multiple people, across networks or the Internet, underscores the importance of making security testing as friction-free as possible, and a complete, maintained OpenAPI file is a key part of that. ### Anything else? OpenAPI spec for OpenAI api -- https://github.com/openai/openai-openapi OpenAPI Specification -- https://github.com/OAI/OpenAPI-Specification A third party OpenAPI spec file for Ollama (last updated 2024-02-02; accuracy unknown) -- https://github.com/davidmigloz/langchain_dart/blob/main/packages/ollama_dart/oas/ollama-curated.yaml
GiteaMirror added the documentationapi labels 2026-04-28 08:55:36 -05:00
GiteaMirror commented 2026-04-28 08:55:37 -05:00
Author
Owner
Copy Link

@Tridu33 commented on GitHub (Nov 7, 2024):

It is necessary to maintain a copy of the OpenAPI specification for the various versions of the OLLAMA interface API, and the usage in the documentation is outdated and incompatible. It may be possible to create an OpenAPI specification folder that allows community users or developers to upload a specification file for a specific version of ollama which can be exported by Postman.

<!-- gh-comment-id:2461260231 --> @Tridu33 commented on GitHub (Nov 7, 2024): It is necessary to maintain a copy of the OpenAPI specification for the various versions of the OLLAMA interface API, and the usage in the documentation is outdated and incompatible. It may be possible to create an `OpenAPI specification` folder that allows community users or developers to upload a specification file for a specific version of ollama which can be exported by Postman.
GiteaMirror commented 2026-04-28 08:55:37 -05:00
Author
Owner
Copy Link

@HavenDV commented on GitHub (Nov 28, 2024):

https://huma.rocks/features/bring-your-own-router/
So far Huma and humagin seem like suitable tools for this, but I don't have the Go experience to implement a PR (which might not be accepted anyway)

<!-- gh-comment-id:2506843746 --> @HavenDV commented on GitHub (Nov 28, 2024): https://huma.rocks/features/bring-your-own-router/ So far Huma and humagin seem like suitable tools for this, but I don't have the Go experience to implement a PR (which might not be accepted anyway)
GiteaMirror commented 2026-04-28 08:55:38 -05:00
Author
Owner
Copy Link

@SuperPat45 commented on GitHub (Apr 8, 2025):

I found a postman collection: https://www.postman.com/postman-student-programs/ollama-api/collection/suc47x8/ollama-rest-api, but it needs to be converted with 3rd party tool

<!-- gh-comment-id:2785744442 --> @SuperPat45 commented on GitHub (Apr 8, 2025): I found a postman collection: https://www.postman.com/postman-student-programs/ollama-api/collection/suc47x8/ollama-rest-api, but it needs to be converted with 3rd party tool
GiteaMirror commented 2026-04-28 08:55:38 -05:00
Author
Owner
Copy Link

@lukebtaylor commented on GitHub (Jun 2, 2025):

Apologies for opening a PR prematurely, I meant to create it against my fork and discuss in this thread before opening. But I clicked to quickly. If there is interest, this PR adds the swaggo annotations and some documentation on building out the openapi specs using swaggo. It does not have the automated build, but it does open the door for that.

<!-- gh-comment-id:2929002449 --> @lukebtaylor commented on GitHub (Jun 2, 2025): Apologies for opening a PR prematurely, I meant to create it against my fork and discuss in this thread before opening. But I clicked to quickly. If there is interest, this PR adds the swaggo annotations and some documentation on building out the openapi specs using swaggo. It does not have the automated build, but it does open the door for that. - https://github.com/ollama/ollama/pull/10946
GiteaMirror commented 2026-04-28 08:55:39 -05:00
Author
Owner
Copy Link

@RubenGarcia commented on GitHub (Feb 26, 2026):

I am also interested in this functionality.

<!-- gh-comment-id:3965696075 --> @RubenGarcia commented on GitHub (Feb 26, 2026): I am also interested in this functionality.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
amd
api
app
bug
build
cli
cloud
compatibility
context-length
create
docker
documentation
embeddings
feature request
feedback wanted
good first issue
gpt-oss
gpu
harmony
help wanted
image
install
intel
js
launch
linux
macos
memory
mlx
model
needs more info
networking
nvidia
ollama.com
performance
pull-request
Mirrored from GitHub Pull Request
 python
question
registry
rendering
thinking
tools
top
vulkan
windows
wsl
No Label api documentation
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/ollama#48590
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?