search

snipe / snipe-it

A free open source IT asset/license management system
https://snipeitapp.com
GNU Affero General Public License v3.0
11.14k stars 3.19k forks source link

OpenAPI Spec / Documentation inaccurate #10328

Open jk1ng opened 3 years ago

jk1ng commented 3 years ago

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 #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[bot] commented 3 years ago

👋 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 commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

(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 commented 2 years ago

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 commented 2 years ago

The schema provided does not match the implementation:

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,

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 commented 2 years ago

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.