OpenAPI / Swagger

just wanted to bump this general theme, and connect some extra dots across other AP-software, since any other projects will have to keep compatibility with at least those three:

pleroma: pleroma#559 (closed)

mastodon: https://github.com/tootsuite/mastodon/issues/1404

misskey: https://github.com/syuilo/misskey/pull/4351

Why is the misskey issue linked? They don't use Mastodon client API last time I checked

b/c it has an API, and (theoretically) can haz clients other than web-ui

Should be probably done with this: https://github.com/open-api-spex/open_api_spex

Not really a fan of it. While it's sometimes convenient to write the spec in the code, it means that you would

1. Need to be an Elixir developer to edit it, harming the re-usability by other projects
2. Need to wait for/implement a wrapper for new features OpenAPI spec gets
3. I just don't like thousand line modules with 800 lines of it being the in-line docs

while I personally like the idea of in-modules docs, my experience with the lib (and a few other alternatives) is not good at all because of 2. mentioned by @rinpatch - it is absolutely true that all such libs will fall behind upstream specs and writing plain openapi.json will always be easier and more powerful option.

@lambadalambda what do you think about going plain specs file?

I find yaml to be nicer for something you write manually, though I am fine with JSON as well

I didn't mean to push for json and absolutely fine with both :)

Well… I prefer JSON than YAML, format is much simpler and doesn't relies on weird-space indentation that can get hard to review. And we already use JSON a lot anyway, we only use YAML for gitlab-ci (and I have to lint it all the time…).

just a side note on json: there's no such thing as multiline strings in it, which can be painful

Some more questions so we can decide on what to use and start working on this

Need to be an Elixir developer to edit it, harming the re-usability by other projects

What other projects are supposed to edit our spec? And can't open-api-spex generate the 'plain' spec files?

Need to wait for/implement a wrapper for new features OpenAPI spec gets

True, but doesn't seem like a big thing.

I just don't like thousand line modules with 800 lines of it being the in-line docs

I suspect this might be your main dislike :) As far a I can see, that's not really necessary, we can have a separate module for these and then defdelegate.

Either way, I'd like to be able to cast and validate params coming in, but I see that you can do the same with plain spec files. Are you opposed to library overall or just to in-module specs? if so, what about in-other-module specs as opposed to plain specs files

Either way, I'd like to be able to cast and validate params coming in

Ah, I missed that it does that when I originally took a look at it. In this case I am for in-module specs

assigned to @chvanikoff

assigned to @egor and unassigned @chvanikoff

mentioned in merge request pleroma!2345 (merged)

closed via merge request pleroma!2345 (merged)

mentioned in commit pleroma@d2e21fbc

Not actually closed. While true that pleroma!2345 (merged) was merged, it does not provide specs for the whole API

Correct, pleroma!2345 (merged) adds specs for AppController only. Perhaps we need a tacking bug for the others?

Yes, that would be good

reopened

mentioned in issue pleroma#1692

unassigned @minibikini