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.
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?
From the documentation it says it supports v2 and v3 of the OpenAPI spec so v2 should be ok.
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 :)
So far that was the only issue I've found. Everything else looks good.
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
updatedhowever this field doesn't exist. Instead it's being returned asedited_at. Can the docs be updated to correct this? Otherwise I will have to manually maintain this difference on my end.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.
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.
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 :)
So far that was the only issue I've found. Everything else looks good.