API Documentation via Swagger / RAML / Others

[Zenithar]

In order to provide more accessible informations about REST API usage, it would be great to have an API specification in Swagger (http://swagger.io/) or RAML (http://raml.org/).

Great job ^^

[Solido]

I guess we can do it ourself using a tool like PostMan and then share the Postman button in the .md of the project for instant view of the API.

[Zenithar]

Check example on https://gist.github.com/Zenithar/21677b5fa3ba73a4c4175e8926683938

[Solido]

This should have higher priority if swagger is ready a lot of client in any languages can be auto written based on it using it as a stub.

[Zenithar]

Check all supported server and client, it is awesome ^^
http://editor.swagger.io/#!/

[csu]

👍 I was just thinking this would be a great idea. We would then be able to generate clients for so many languages, without having to write them all separately. Plus, some client libraries are already falling behind on API changes. With swagger, we could just regenerate them to keep them up-to-date with the latest API changes.

[muffinista]

Hi! This is an old issue obviously, but I'm interested in helping to move it forward if there is still interest. I've used Swagger to generate clients a few times now, and have also implemented it for APIs once or twice in Rails.

I think implementing Swagger makes a lot of sense for Mastodon -- there's a bunch of clients out there, but the API is growing and changing, so it's challenging to keep up.

There's a couple of gems in ruby to help generate a swagger API, although they all operate a little differently . I've used swagger-blocks, and it works pretty well, but requires you to write a certain amount of boilerplate code in the app. I haven't used rswag, but it looks interesting. It operates via integration tests which is pretty cool.

For kicks I made a gist of a diff of the codebase to add swagger-blocks and define GET /api/v1/statuses/:id. It's pretty rough but it gives you an idea of how it might work.

[pawelngei]

👍 to Swagger for Mastodon, I think we need it badly if we want to have more developers working on the code.

[danhunsaker]

Just gonna point out that Swagger is now OpenAPI, and has become the de facto standard for this.

[pawelngei]

I'm still learning Ruby, but I started trying out https://github.com/fotinakis/swagger-blocks/ .

Should OpenAPI be available only in development, or in production as well?

[danhunsaker]

The OpenAPI spec file can be generated in any of a number of ways, but is only really useful to developers trying to make use of an API in their own code, so there's not really any reason to deploy it into production. That said, that doesn't necessarily mean there's any reason not to, either. It'll probably come down to preference, but I'd say automate creating an OpenAPI spec file in development, and make a rake task to generate one in production.

[pawelngei]

Okay, after checking out several different solutions I'm really surprised that Rails doesn't allow automatic endpoint discovery and documentation like Django does.

What I previously estimated as a "3 points" ticket turned into 21. I think I won't be able to finish it this year.

[danhunsaker]

Most language tooling involves docblocks or other forms of annotations. There's quite a bit of nuance that can be presented in a spec file but not easily autodetected.

[lukepighetti]

Hi everyone, did this end up going anywhere? We'd like to generate a Dart API off a Mastodon OpenAPI specification if possible.

[JasonHK]

I suggest creating a separate repository to store the OpenAPI definitions like what github/rest-api-description do.

[lukepighetti]

We're deprecating the Dart client until a first-party Mastodon OpenAPI spec is provided.

lukepighetti/mastodon_dart#39

[LoveIsGrief]

This would be a great feature to have as even the python client isn't being updated due to lack of time by the maintainer. It need not be this was as the client libraries could be generated and publish automatically using the OpenAPI Generator.

Client libraries could be generated in nearly every mainstream language (Python, JS, Java, Rust, Go, PHP, and the list goes on).

Does Ruby on Rails not have any library to annotate endpoints with to generate an OpenAPI spec from?

[trwnh]

is there a way to represent a variable for the thousands of mastodon servers out there? because i'd be willing to put in the effort if there is -- it's just that, based on my level of knowledge, this has been a major blocker toward this effort.

[LoveIsGrief]

@trwnh what do you mean by "represent a variable for the thousands of mastodon servers"? Generated client libraries will be able to target whichever domain they want, if that's what you mean.

[trwnh]

@trwnh what do you mean by "represent a variable for the thousands of mastodon servers"? Generated client libraries will be able to target whichever domain they want, if that's what you mean.

what i mean is, can you get away with not including the servers block?

[LoveIsGrief]

It's optional, but it shouldn't be difficult to fill for the instance running it. For the generator, it doesn't matter since the generated client allow people to target whoever they want.

[trwnh]

It's optional, but it shouldn't be difficult to fill for the instance running it. For the generator, it doesn't matter since the generated client allow people to target whoever they want.

so then, every mastodon server has to host its own OpenAPI spec document? there's no way to (for example) host one centralized definition on docs.joinmastodon.org?

[LoveIsGrief]

@trwnh It can be implemented as a simple endpoint e.g /v1/openapi.json. That endpoint can generate the spec on-demand or point to a file generated by a rake command.

I don't think it would be good for the spec file to be written by hand and should be generated from the endpoints themselves. Django Rest Framework does it and Ruby is also a scripting language that allows a lot of reflection. Generating a spec from the routers might already be a gem (I'm not a rails dev but maybe these are candidates rswag-api, openapi-rails, rswag) or could the algorithm could be written manually.

For use with openapi-generator and generation in the CI, it would be best to also have a rake command.

[andypiper]

I’ve just done a quick search but I don’t see a Postman Collection for Mastodon APIs - that could have the server as a variable to be substituted in depending on the instance.

I’m not entirely clear on how the API works in relation to the federation - are e.g. search queries only run against Toots that are available on a a specific instance, or do they fan out somehow?

All of this is to say +1 for an OpenAPI spec, and I think a consistent endpoint on each instance that served up the document would be the simplest solution.

[lukepighetti]

I'm honestly very surprised that there isn't an OpenAPI spec for Mastodon, when the goal is decentralized servers and (I thought) clients. I'm a firm believer that all backend services should write contracts, as it reveals unintentional complexities, and reduces confusion for front-end developers. That allows folks to build clients faster with less support requests.

OpenAPI just happens to allow us to generate stateless clients for pretty much every language imaginable, and setup CI to keep them 100% up to date.

From that point, maintainers are left with building caching systems or workflows to achieve common tasks. This lowers the barrier for new app developers to build great products.

It also solves the 'undocumented endpoint/field' problem, which has shown up in the past.

And I believe there are tools to even generate mock servers with Postman. (I actually got temp banned from mastodon.technology for posting 3 "testing" messages to my personal timeline because it was too time-intensive to spin up my own server at the time.)

I strongly believe that an OpenAPI spec is a reasonable ask, and that it would provide endless return on investment in both the quantity and quality of integrations with Mastodon. I cannot think of a single benefit to not having one, unless the goal is fewer 3rd party clients.

[FelisNivalis]

I created a repo and added a few apis. Maybe we can start and maintain a version first?

[oneslash]

Hi everyone,

I have finished today the API specification (except the streaming API): #20000

Would be great if you can help to test and review.

[pawelngei]

@oneslash thank you so much for that! I'm afraid that my knowledge of Mastodon API got pretty rusty and I won't be able to help (at least this month), but I'm keeping my fingers crossed for you, absolutely awesome work ❤️

[oneslash]

Hi everyone,

After the discussion in the PR I have linked, there was a proposal to use the https://github.com/zhandao/zero-rails_openapi library to generate OpenAPI specifications from the code itself. I do not have RoR experience. If someone can contribute to the project using the library linked or another library, that would be great.

[pawelngei]

@oneslash I arrived at the same point four years ago, but I wasn't aware of zero-rails_openapi then. If we can generate the API docs automatically, it's absolutely great!

I still don't know Rails ._.

[petecheslock]

Hey Folks - I had started #22314 last year on this topic of automating OpenAPI. I wrote a post recent showing how we can use AppMap for Ruby to record the Mastodon rspec test cases and then export this data to an OpenAPI v3 specification file.

Let me know if this is helpful to anyone. https://dev.to/appmap/automatically-generating-openapi-docs-for-mastodon-42ig

We'd be happy to submit a pull request or help the team out /cc @kgilpin