14 v1 API endpoints missing from the OpenAPI spec — happy to document them

[qmarquez]

Hi James,

While exploring the API I noticed a handful of v1 routes that exist in routes/api.php (branch develop) but are not present in the published OpenAPI spec (dist/firefly-iii-develop-v1.yaml in api-docs). I'd be happy to contribute documentation for them, but I'd like to align on the right approach first.

I found the gap by diffing the real routes against the spec:

• 181 unique paths in routes/api.php
• 164 documented paths in the spec
• 14 real endpoints with no matching path in the spec

Undocumented endpoints

subscriptions resource (alias of bills) — the biggest gap:

GET, POST       /v1/subscriptions
GET, PUT, DELETE /v1/subscriptions/{bill}
GET             /v1/subscriptions/{bill}/attachments
GET             /v1/subscriptions/{bill}/rules
GET             /v1/subscriptions/{bill}/transactions
GET             /v1/data/export/subscriptions

User group / administration management:

PUT   /v1/user-groups/{userGroup}/update-membership
POST  /v1/user-groups/{userGroup}/use

Miscellaneous:

GET   /v1/currencies/default
GET   /v1/currencies/{currency_code}/cer
GET   /v1/piggy-banks/{piggyBank}/accounts
POST  /v1/recurrences/trigger
GET   /v1/rules/validate-expression
GET   /v1/search/transactions/count

Question before I open a PR

The spec in api-docs seems to be committed via an automated "🤖 Update API documentation" step. Could you clarify how it's produced?

• If it's generated from annotations in the code, I should add the missing annotations in firefly-iii itself.
• If the YAML is hand-edited, the PR would go to api-docs directly.

Knowing this will let me send the PR to the right place. I'm happy to start with the subscriptions resource as a first, self-contained PR.

Thanks for all your work on Firefly III!

[JC5]

Hey, thanks for starting this discussion.

Thanks for your offer! Your help would be greatly appreciated. And yes, the API docs are generated from api-docs. The src directory holds all the partial yaml files that are stitched together using a script that lives in api-docs-generator. If you edit the source files, or create new ones, they are automatically included in the new output. My work right now is to make this process automated, but I've not yet found the time.

If you create a PR in the api-docs repository I will be happy to review and merge. Check out the other files to see what's happening code wise.

Cheers,
James

[qmarquez]

Thanks James! I've opened the first PR covering the subscriptions resource: firefly-iii/api-docs#16

Since /v1/subscriptions is served by the same Models\Bill controllers as /v1/bills, I mirrored the existing bills partials (reusing their schemas and the bills tag) and added /data/export/subscriptions. I couldn't run api-docs-generator locally (no PHP on hand), so I relied on YAML validation and matching the working bills files — let me know if the stitched output looks off.

I'll send the remaining endpoints (user-groups membership, currencies/default, currency rates, etc.) as follow-up PRs.

[JC5]

Sounds great! I will have time over the weekend to do an actual review and merge, but it looks great. Were the _tpl_ entries confusing or weird, or did it make sense?

[qmarquez]

Sorry for the slow reply — I got caught up with work stuff.

The _tpl_ entries made sense fairly quickly: the README explains them well (template name + indentation level), and mirroring how bills.yaml used them made it mostly copy-and-adjust. The only small friction was getting the indentation number right by hand — it's easy to mismatch the nesting level and only notice it in the stitched output. Not a blocker at all, just the one thing a newcomer has to pay attention to.

I'll set up api-docs-generator locally for the follow-up PRs so I can verify the stitched output myself before sending them your way. And I'd be happy to contribute more broadly once I'm done with the documentation work — just let me know where it'd be most useful.

[JC5]

Nice work, it's merged!

[qmarquez]

Quick update: I just opened #17, which documents the five remaining v1 GET endpoints (/currencies/default, /currencies/{code}/cer, /piggy-banks/{id}/accounts, /rules/validate-expression and /search/transactions/count). Together with the already-merged #16, that should close the documentation gap from this discussion — every active v1 route now has a corresponding entry in the spec.

This time I set up api-docs-generator locally (PHP 8.4) and confirmed the stitched output builds cleanly with all the new paths included, so review should be smoother on your end.

I'd love to keep helping — is there anything on your end I could take off your plate? A good-first-issue, something in the API/docs area I already have context on, or whatever is most useful to you right now.

If there's nothing in particular where I'd have the most impact, I do have one idea I'd be happy to propose: improving the search experience. The search documentation is clear about how to build queries, but in day-to-day use it's a bit cumbersome to have to keep the docs at hand to run more complex queries or search on specific fields. I think there's room to make that smoother for users, and I'd be glad to write up a concrete proposal first so you can decide whether it's worth pursuing before any code. 🙌

Thanks for building and maintaining all of this, James!