Core: Add Swagger 2.0 support

[dunglas]

[teohhanhui]

Is there any action that we need to take on our end? I thought Swagger support should fall under NelmioApiDocBundle?

Or is this referring to using the Swagger spec for validation? Generating resources / operations based on the Swagger spec?

[dunglas]

Nelmio only support the Swagger v1 spec. And, as API Platform is now a standalone library, it would be nice to have native Swagger, support not relying on an external Symfony bundle.

Or is this referring to using the Swagger spec for validation? Generating resources / operations based on the Swagger spec?

Yes.

[teohhanhui]

Related: https://blog.liip.ch/archive/2016/05/11/convert-nelmioapidocbundle-to-swagger-php.html

[dunglas]

Yes, and this tweet: https://twitter.com/couac/status/730415066047234049

I've looked at this lib, it's not practical for API Platform (it relies on external annotations). Adding native Swagger support would be better.

[teohhanhui]

The problem I ran into when I first tried Swagger (v2) was that you have to maintain the spec separately. That's where annotations can help by auto-generating the Swagger spec based on @ApiResource and @ApiProperty.

[teohhanhui]

What I mean is that it's easier to do it code-first instead of schema-first.

[dunglas]

NelmioApiDoc has officially been deprecated: https://github.com/nelmio/NelmioApiDocBundle/releases/tag/2.13.0

[teohhanhui]

@dunglas:

NelmioApiDoc has officially been deprecated

No, it has not. He is "thinking about" it.

[teohhanhui]

In any case, if we can have dynamically generated Swagger spec (or exported by a console command or similar) based on API Platform metadata then I'll be happy.

[dunglas]

Ok but it is at least feature frozen... It's time to move on.

[Simperfit]

@dunglas this can be closed

[soyuka]

@Simperfit Hmm I'd leave this open, I see a few things left:

• swagger-ui can not stay in the repository, it's dirty 😛 (I saw something about it not beeing packaged can't remember where)
• Is the NelmioApiDoc bridge still required?

[Simperfit]

@soyuka I disagree with you about swagger-ui, why not ? It has alot of features and can stay in this repository.

You are right about the bridge

[soyuka]

Can't it be a dependency? Because it sux for updates and maintenance. I'm sure we can add some post install script in composer to fetch it, couldn't we?

[teohhanhui]

@soyuka:

Can't it be a dependency? Because it sux for updates and maintenance.

It sucks for trying to search in the repository too. We should definitely fix this before 2.0 release.

[soyuka]

+1
Le lun. 1 août 2016 à 10:42, Teoh Han Hui [email protected] a
écrit :

@soyuka https://github.com/soyuka:

Can't it be a dependency? Because it sux for updates and maintenance.

It sucks for trying to search in the repository too. We should definitely
fix this before 2.0 release.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/api-platform/core/issues/538#issuecomment-236522471,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABQr8_5h4MVzXzAdN32bMUvUbwebS6cGks5qbbFvgaJpZM4Icw0P
.

[soyuka]

Fyi you can use path: with github but still agree 200%
Le lun. 1 août 2016 à 11:01, Soyuka [email protected] a écrit :

+1
Le lun. 1 août 2016 à 10:42, Teoh Han Hui [email protected] a
écrit :

@soyuka https://github.com/soyuka:

Can't it be a dependency? Because it sux for updates and maintenance.

It sucks for trying to search in the repository too. We should definitely
fix this before 2.0 release.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/api-platform/core/issues/538#issuecomment-236522471,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABQr8_5h4MVzXzAdN32bMUvUbwebS6cGks5qbbFvgaJpZM4Icw0P
.

[dunglas]

It's on my todo list, I think @soyuka's solution is a good trade off: move Swagger UI assets from core to the standard edition.

What do you think?

[soyuka]

@dunglas won't there be a way to release a builded swagger-ui to packagist? This would be the cleanest solution IMO.

[dunglas]

Probably but it looks overkill. And is a pain to maintain.

What we can do is install Swagger UI in the standard edition using NPM or Bower (I prefer the first one) and create a hook in composer.json to update JS dependencies if NPM and related stuffes are installed.

[teohhanhui]

I've made the suggestion at swagger-api/swagger-ui#2310

[teohhanhui]

Swagger UI is now published at https://packagist.org/packages/swagger-api/swagger-ui

[soyuka]

This is great! Thanks @teohhanhui!

[dunglas]

Great but how can we put it in the right (public) directory?

[teohhanhui]

@soyuka is working on it in #768 :smile: