There are a number of standards for describing APIs, one of them being Swagger. I am developing an approach to API development with PHP that will allow for automatically generate Swagger definition of the API, together with the underlying schemata. With this approach, it is possible to generate Swagger definition automatically from a deployment pipeline, failing in case of certain inconsistencies. Combined with the Swagger client code generator, you can also update your API client for free and also fully automatically.


Comments are closed.

It was nice to hear about different API documentation options. The difficulty with the subject is probably that it's a bit dry, so as an attendee I found it hard to stay focused. This problem also had to do with the time of the day - second conference day, final talk slot (and in my case, immediately after my own talk ;)). Something you can't do anything about. I'd still look for ways to make the slides and the talk more lively. Try to get away from the laptop, try to look around more, make some more fun while "on stage". Good luck with your speaking efforts!

I think that this is an interesting subject as a lot of people work with API's these days.
Like Matthias said, this is a bit of a dry subject and the time of day was a bit against you.

Some suggestions on how you could try to improve it:
- Add some more color to the slides (Don't make it a colouring book), the slides now were a bit plain.
- With a room as wide as this one I think it's a good idea to walk around a bit from side to side. This will give the audience a focus point when they are done looking at the current slide.
- Interactivity is also a good way to add more vibe to a dry subject like this
- And if you're up to it you can always add a little humour

Now these are just suggestions. Play around with them and try to find what works for you. You'll get there! Good luck!

Good to see another take on generating APIs documentation. I'm used to things like Nelmio.

I think missing from at the the start was a brief overview of how other tools approach the problem and why the need for the approach you outlined.

For example other API documentation tools that I have used use the annotations to get this information. If the annotations are also used to generate the routes then it is likely that the documentation generated will be correct.
The approach of returning an array with this information can leave the actual and documentation out of sync with each other. I spent a lot of the first half of the talk wondering why annotations were not being used. A little bit at the start explaining what is missing from existing solutions would probably have helped me,

As an aside: I see benefits for the method of API documentation generation you mention in fact I wonder if a hybrid approach would work best. Getting as much routing, parameters and return type information from annotations or router information, code reflection, etc and add the ability to override or add additional information via code (as your tool does)?

Interesting to see different ways of working. Thanks for the talk.

Steve Winter at 22:49 on 11 Jun 2018

Congratulations on your first talk in English - I admire anyone who can stand in front of an audience and present, even more so in 'another' language!

You've built a really interesting looking tool which I'm keen to investigate further so well done there.

I would have liked to have seen some 'real' code (rather than screenshots) and a demo which produced the swagger documentation. Given that there are also other tools out there intending to achieve the same thing, but which work in a different way, would be good to include a comparison.

Arnout Boks at 19:27 on 14 Jun 2018

For me the talk felt a bit low on content. I would have liked some more background and insights on Swagger/OpenAPI and what is possible with that. You seem to know what you're talking about very wel, it's just that a limited scope has quite limited usefulness to a broader audience. Good luck with you next talks!