Mautic Community Forums

Swagger/OpenAPI support for Mautic API

My idea is:

Swagger/OpenAPI would allow the developer API docs to be generated/updated automatically as soon as an API endpoint/model changes, and it will become possible to generate API clients for multiple languages (PHP/Java/JavaScript/etc.). This Symfony bundle might help a lot: https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html

I think these groups of people would benefit from this idea:

People who are using the Mautic API to connect to Mautic instances

Why I think they would benefit from this idea:

Improved/more up-to-date API documentation, as well as the possibility to generate API clients (PHP/Java/JavaScript/etc.) on the fly if necessary

Any code or resources to support this idea:

https://swagger.io/docs/specification/about/
Examples: https://editor.swagger.io/

Are you willing to work on this idea?:

Yes

What skills and resources do you need to explore this further?

Let’s wait for the final version of Mautic 3 before discussing this topic further.

Did some first work today to enable Swagger on Mautic 3, and it’s going well!

Was able to generate a JSON spec file which has all the endpoints in it:

https://trello-attachments.s3.amazonaws.com/5dde6d0feb0e5f19e46b96fd/5e4bcfadd30b5f6dd4f4cbd5/b331959cbd6938a773d51c88354bff05/mautic-swagger.json

If you go to https://editor.swagger.io and upload the JSON file there, you’ll be able to visually see the available endpoints there:

Next step is to start linking the right data models to all the endpoints. But this is a great first step!! :tada:

2 Likes

I have some experience with https://symfony.com/doc/current/bundles/NelmioApiDocBundle/index.html and it worked like a charm. For frontend we used great https://redocly.github.io/redoc/

2 Likes

Yes I’m using the NelmioApiBundle (see https://github.com/dennisameling/mautic/commit/662bb0a5efe65289e923692705f0095a7152d468). I came across ReDoc as well, looks good! Will first need to make sure that the Swagger spec generated by Mautic is as complete as possible, will work a bit more on it during the weekend. Thanks for your input :slight_smile:

1 Like

In some scenarios it is kind of tricky to describe an endpoint via Nelmio annotations to get desired output. If you are stuck, feel free to ask me. I may help you.

1 Like

There’s some roadblocks I ran into after spending some hours on researching the internals of both Mautic and the NelmioApiBundle. I have documented them here:

@fedy if you’d have some time to look into this as well, that’d be fantastic. I’ll try to spend some time next weekend to to continue diving into this.