Swagger/OpenAPI support for Mautic API

Ideas and Feature Requests
1

My idea is:

UPDATED June 2nd 2020, see this comment

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.

2

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:

image
image928×889 39.3 KB

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

2 Likes
3

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
4

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
5

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
6

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.

7

Just had a call with @dongilbert and we’ll try to harmonize efforts for implementing OpenAPI between Acquia and the community, so that we’re all on the same page. We expect to move into the direction of introducing a new API version (v2) using API Platform, which will make maintenance a lot easier for all parties involved, make the API more predictable/stable and will help us to automatically generate OpenAPI docs. A migration path from the old API will of course be provided.

We’re trying to get the requirements clear within the next 30 days (roughly) after which we’ll be looking for community contributors to get this project moving forward. If anyone has thoughts on this idea or would like to help, please do not hesitate to leave a comment here! To be continued :rocket:

3 Likes
8

Hi,

Is there any news on this? I’m looking to move my clients from Dotmailer to Mautic but my main sticking point at the moment is lack of api sdk’s (primarily java). I’ve had a go generating both a java & spring client with swagger using your json file but it just errors. I’m about to start building a java sdk for my needs but figured I’d see if there was any update on the API-Platform collaboration before I begin.

All the best
Ash