OpenAPI Spec / Documentation inaccurate

[jk1ng]

Snipe-IT Version

5.1.8

Operating System

Ubuntu

Web Server

Docker

PHP Version

N/A

Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Hi!

The current OpenAPI v3 spec that is released on https://snipe-it.readme.io/openapi/ could be improved:

1. Ideally, the spec should be included on the actual server (e.g., /api/v1/openapi.v3.json or something to that effect), and ideally generated from code (I'm not familiar with Laravel and how much of a pain that might be)
2. Some of the API documentation does not match up with the actual functionality. For example, fields and fieldsets ( Issue Creating custom fields (NOT FieldSets) via the API #8311 )

This would also generally improve QoL for integrators e.g., with issues such as #7900 and #9932 which were closed but could be argued as unaddressed at the time.

I'm not sure if this is automatically included in the upcoming v6 release, but I didn't see it mentioned (or screenshotted) in the roadmap:
https://grokstar.dev/news/snipeit-releases/2021/07/snipe-it-v6-roadmap/

-- so my hope is that by raising this now, maybe this is something that can be prioritized at some point for v6.

Thanks!

Describe the solution you'd like A clear and concise description of what you want to happen.

1. OpenAPI v3 JSON spec should be generated at first install/setup time, from the actual code, and cached on the server at an endpoint such as /api/v1/openapi.v3.json
2. Documentation for the API should better match actual API behavior

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered.

No response

Additional context Add any other context or screenshots about the feature request here.

I'm not sure what the current quality is for Laravel <-> OpenAPI spec generators, but it seems that there are a few open source projects that are out there which do this. In the Python world, one of them which works really well is https://flask-restx.readthedocs.io/en/latest/ -- maybe something to this effect can be used to auto-generate the spec on the server for v6?

[welcome]

👋 Thanks for opening your first issue here! If you're reporting a 🐞 bug, please make sure you include steps to reproduce it. We get a lot of issues on this repo, so please be patient and we will get back to you as soon as we can.

[snipe]

There isn't an easy way for us to generate any of our documentation. It's all hand-written by the devs to write the API. Unless you have specific documentation requests, I'm not sure what you want me to do with this GH issue.

[jk1ng]

Oh wow, that sounds like a lot of work.

Is there any chance an automatic generation of OpenAPI spec from your Laravel app could be possible in the future? e.g.:

1. https://blog.quickadminpanel.com/laravel-api-documentation-with-openapiswagger/
2. https://vyuldashev.github.io/laravel-openapi/
3. https://github.com/mdwheele/laravel-openapi

This would reduce the need for hand-written documentation and would ensure a 1:1 match between the API spec and the underlying code.

[snipe]

I'm familiar with those, but the integration with our documentation platform (readme.io) is a little trickier. They do have some abilities to import things like Swagger, etc, but last I checked it was still kinda manual :(

[snipe]

(I will definitely look into this tho - last time I looked - which was admittedly a few years ago - it wasn't so simple, but that definitely may have changed since then.)

[jk1ng]

That would be pretty awesome!

I think if there was a way to have the Snipe-IT application host OpenAPI v3 JSON files locally (e.g., at /api/v1/openapiv3.json) that would already be a big deal. The documentation could then be updated to say something to the effect of "If you need access to the current OpenAPI v3 JSON files, versioned copies are hosted at XYZ, but otherwise you can access them directly on your server where they will be accurate for your specific Snipe-IT version."

[commonism]

The schema provided does not match the implementation:

• security: [] for PathItems allows usage without authentication
• no components.securitySchemes,
• global security: []

With these, the client can not authenticate properly to the service, as use without authentication is permitted by the description document.

Removing security: [] from pathitems and …

ctx.document["security"][0] = {"bearerAuth":[]}
ctx.document["components"]["securitySchemes"]["bearerAuth"] = {"type": "http", "scheme": "bearer"}

Once you can authenticate,

• the use of empty schemas for properties
• using "-" in operationIds

does not play well with many OpenAPI clients.

A benefit wrt. to structure would be using components and having the operationIds in the online Swagger doc would improve usability as well.

[uberbrady]

The best way I can see us pulling the OpenAPI JSON files into the app would be some kind of triggered GitHub action thingee that pulls down the appropriate version from readme.com, and then adds it into the repo. One thing to note is that that readme spec file is quite aggressively cached right now, so I'd worry that sufficiently recent changes to the API docs might not be correctly reflected in the app. But, again, that is something that I would consider adding in if the process could be automated.

[Gunn1]

I'm currently working on generating a client for the Snipe-IT API using Swagger Codegen/OpenAPI Generator, but the OpenAPI spec currently provided (v8.0.3, OpenAPI 3.1.0) has a few structural issues that make it incompatible with OpenAPI tooling:

---

🔒 Authentication Schema Issues

1. components.securitySchemes is present but completely empty.
2. security at the global level is set to [{}], meaning no security is enforced globally.
3. Most paths and operations (e.g. /hardware, /hardware/{id}) explicitly include "security": [], allowing unauthenticated access per the spec — which is incorrect.

Because of this, Swagger Codegen and OpenAPI Generator generate clients without any authentication support, leading to invalid requests.

✅ Suggested Fix

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

Alternatively, in JSON patch format:

ctx.document["security"][0] = {"bearerAuth":[]}
ctx.document["components"]["securitySchemes"]["bearerAuth"] = {"type": "http", "scheme": "bearer"}

---

⚠️ Other Structural Issues

• Many properties contain empty schemas {}, which can cause codegen tools to fail or ignore fields.
• Several operationId values contain hyphens (e.g. hardware-create, hardware-list), which break method generation in languages like Python or TypeScript.
• The file does not make use of reusable components like schemas, parameters, or responses for consistent structure.
• Swagger UI does not show operationIds, reducing developer usability for SDK generation and debugging.

---

✅ Suggested Actions

• Define bearerAuth in components.securitySchemes.
• Apply it at the global level via security, and remove security: [] from individual path items unless explicitly unauthenticated.
• Replace operationId hyphens with underscores or camelCase (hardwareCreate, hardwareList, etc.).
• Replace {} placeholders in schemas with appropriate types or use nullable: true with a type.
• Use $ref and components to improve maintainability and tool compatibility.

---

[snipe]

Our OpenAPI files are generated by readme.io, so I’m not sure how we’d implement this exactly. I’ll have to see if they have additional configuration options.

[commonism]

I'd consider dropping the generation, the generated description document has been broken for years, it's way to complex to address the generation, so nobody cares.
I propose to use the current generated document as a starting point and maintain it manually, simply include the openapi.yaml in the repo.
Will be trivial to make changes to the description document, it's more likely to match the protocol implemented than the generated description document.

Having unit tests helps to make sure the description document matches the protocol implemented.
I'm with a python openapi3 client library and I'd contribute the required frame for unit testing within the github ci.