While adding PieFed support to Summit, I used a utility to convert swagger docs to source code and ran into an error in the docs. The docs state that objects like Post, Comment have the field updated however this field doesn't exist. Instead it's being returned as edited_at. Can the docs be updated to correct this? Otherwise I will have to manually maintain this difference on my end.
this post was submitted on 18 Jul 2025
4 points (100.0% liked)
PieFed API & mobile app dev
89 readers
4 users here now
Announcements and discussions about the PieFed API - changes, improvements and general co-ordination between the frontend developers and the core of PieFed.
founded 3 weeks ago
MODERATORS
The GitHub repo is here; you could submit a PR. I’m also auto-generating source code from the Swagger docs :)
afaik the swagger docs are manually updated, not automatically generated from our code so it's not really a current/reliable enough 'source of truth' to be feeding it into your codebase. @andrew_s@piefed.social can you let us know how this works?
Mlem dev here.
it's not really a current/reliable enough 'source of truth' to be feeding it into your codebase.
I’m auto-generating the code from the API docs, the same as @idunnololz is. As you say, it’s not really reliable at all. This is a major pain point for us at the moment.
For Lemmy we’re auto-generating our own source code from the Lemmy source code, which means that we can stay perfectly up-to-date with whatever Lemmy changes. Our script goes through the git history of the backend and finds when a certain feature was added to the API, then adds a comment in our source code explaining that. This saves us an enormous amount of time.
Unfortunately, the PieFed source code isn’t structured in a way that makes auto-generation feasible, so we use the API docs instead.
Because the API docs aren’t versioned and aren’t guaranteed to be correct, there’s a significant development overhead compared to Lemmy support. If there’s a new PieFed feature I want to support, I have to go digging through the PieFed git log to find which PieFed versions support it. I then have to comment my code manually to include that information.
In an ideal world, the PieFed docs would be kept perfectly up-to-date: whenever a change is made to the PieFed source, a matching change would be made to the docs at the same time. This would massively improve our development experience. It would also be great if the API docs repo had git tags for each PieFed version, so that we can traverse the git history in the same way we do for Lemmy.
I understand this may not be a reasonable request given how busy PieFed development is, but I thought I’d let you know what my pain points currently are and what could be done to alleviate them. I’m happy to keep doing it the way I am now, I just wish it was a little simpler to keep track of API changes :)
Since your comment we've been looking into what it would take to auto-generate the swagger docs. The package we're thinking about using produces OpenAPI v2 json but I understand there is now OpenAPI v3 that people have been using for a while. Do you have a need for v3 or would v2 be ok?
Thanks for looking into it :)
I don’t have a need for v3, but I’d caution that you might do - v2 is missing quite a few features compared to v3. For example, Swagger v2 doesn’t support oneOf, allOf and anyOf. I believe you’re using some of those in the docs currently? I’d check but I’m not near a computer right now. I’m happy using v2 if you’re happy with it.
Edit: oops, typed some of the versions numbers the wrong way around. Apologies for any confusion
So far that was the only issue I've found. Everything else looks good.
Since your comment we've been looking into what it would take to auto-generate the swagger docs. The package we're thinking about using produces OpenAPI v2 json but I understand there is now OpenAPI v3 that people have been using for a while. Do you have a need for v3 or would v2 be ok?
The tool I'm using to generate code from an OpenAPI spec is this one: https://github.com/OpenAPITools/openapi-generator.
From the documentation it says it supports v2 and v3 of the OpenAPI spec so v2 should be ok.