Nelmioapidocbundle: Support for OAS 3.0

[majermi4]

Hello,

our company has been using NelmioApiDocBundle 2.x and now we would like to move to Swagger/OAS and so we were experimenting upgrading to 3.x. However, we found out that the library used to build the apidoc output ("exsyst/swagger") only supports OAS 2.x but we would prefer to go straight to OAS 3.x so that there is no redundant work if we want to teach our client code to parse our APIs.

Are there any plans to add support for OAS 3.x in the near future or at all? Thank you!

[GuilhemN]

https://github.com/nelmio/NelmioApiDocBundle/pull/1416 removed the dependency on exsyst/swagger so there isn't so much left to do to support 3.0. I don't think I'll have the time to do the changes in the near future but PRs are welcome if anyone wants to do it :)

[namoscato]

@GuilhemN, do you have any plans to support 3.0 since you last posted? Any high-level idea as to what would need to happen?

[GuilhemN]

My answer is the same: I won't be able to dedicate this time in the near future.
The dependency in the dev branch must be bumped and all annotations use updated to be in sync with the 3.0 specification (since we rely on zircote/swagger-php which is already up to date, this is in big part changing properties used/methods called).

[namoscato]

@GuilhemN, no worries – thanks for the response! I might try to get something going on this front myself and will certainly orient myself with the state of the dev branch before doing so.

[namoscato]

@GuilhemN, I took an initial pass at updating annotations.

As I started to update unit tests, there are a few apparent changes worth surfacing:

1️⃣ OpenAPI 3 standardizes the concept of "definitions" into "components". Therefore, things like #/parameters/ are now #/components/parameters/ and @SWG\Definition() is now @OA\Schema().

I first ran into this when updating Util::getIndexedCollectionItem unit tests in which this is no longer valid:

https://github.com/nelmio/NelmioApiDocBundle/blob/00554e1b60bee71f0e8953db3569dde48e606708/Tests/SwaggerPhp/UtilTest.php#L283-L292

While I can try to work through things as I stumble across them, do you have any initial thoughts as to how this will affect things? Should "definition"-related method names and whatnot be updated to "schema"?

2️⃣ zircote/swagger-php's 70316e3 updates all default annotation property values to an UNDEFINED constant to support null values. It seems this will require some updates as well, i.e.

https://github.com/nelmio/NelmioApiDocBundle/blob/00554e1b60bee71f0e8953db3569dde48e606708/SwaggerPhp/Util.php#L216

might have to be updated to something like:

if (UNDEFINED === $parent->{$property}) {

Do you have any initial thoughts as to how this will affect things?

[GuilhemN]

Thanks for giving it a try :)

While I can try to work through things as I stumble across them, do you have any initial thoughts as to how this will affect things?

As definitions are dealt with the ModelRegistry, it should hopefully only affect it (model describers already accept Schema so it should be fine).

Should "definition"-related method names and whatnot be updated to "schema"?

If I'm correct all these methods are internal so it should be ok to update them without adding another difficulty to the upgrading process :)

Do you have any initial thoughts as to how this will affect things?

We often deal with null to make sure we don't erase user's configuration, like for instance in the FosRestDescriber

https://github.com/nelmio/NelmioApiDocBundle/blob/0e72b64e3c32afed8e852401c35f52a5060b90a8/RouteDescriber/FosRestDescriber.php#L61-L66
Or
https://github.com/nelmio/NelmioApiDocBundle/blob/75cf1201ed4d5d6fbb965fba10429f119b989097/RouteDescriber/PhpDocDescriber.php#L50-L55
Or https://github.com/nelmio/NelmioApiDocBundle/blob/master/Describer/DefaultDescriber.php, https://github.com/nelmio/NelmioApiDocBundle/blob/master/ModelDescriber/ObjectModelDescriber.php#L76, https://github.com/nelmio/NelmioApiDocBundle/blob/master/ModelDescriber/JMSModelDescriber.php#L114, https://github.com/nelmio/NelmioApiDocBundle/blob/dev/ModelDescriber/Annotations/PropertyPhpDocReader.php#L56, https://github.com/nelmio/NelmioApiDocBundle/blob/dev/ModelDescriber/Annotations/SymfonyConstraintAnnotationReader.php#L112

I think this is all places needing an update

[namoscato]

Thanks, @GuilhemN – that information certainly helps!

[namoscato]

@GuilhemN, so I made it through most of the unit tests but am hung up on some functional tests at the moment. I am specifically interested in your thoughts around how to handle the ModelRegister's implicit usages of @Model:

https://github.com/nelmio/NelmioApiDocBundle/blob/00554e1b60bee71f0e8953db3569dde48e606708/SwaggerPhp/ModelRegister.php#L57-L68

While I _think_ I understand the purpose of this code, how should things evolve with OpenApi 3?

Response

With Schema now living under content, should you still be able to nest @Model directly under @Response like so:

@OA\Response(@Model(type=User::class))

or should that be nested under content's MediaType?

RequestBody

RequestBody replaces body and formdata _parameters_; therefore, I am assuming we would want to account for that? Should we continue to support Parameter?

Thank you in advance for your input!

[GuilhemN]

@GuilhemN, so I made it through most of the unit tests

That's impressive!

With Schema now living under content, should you still be able to nest @Model directly under @Response like so:

@Model should be accepted under @MediaType but I'm not sure what to do about nesting it directly under @Response.
It seems annoying to specify the mime type on each route though so maybe we could provide a config option default_mime_types to put @Model under those, what do you think?

RequestBody replaces body and formdata parameters; therefore, I am assuming we would want to account for that?

That'd be great, we may want to experience it a bit first though to see how we could implement this the most efficiently, what do you think?

Should we continue to support Parameter?

I think so, it is still useful to describe query parameters

[namoscato]

It seems annoying to specify the mime type on each route though so maybe we could provide a config option default_mime_types to put @Model under those, what do you think?

I realized zircote/swagger-php actually exposes some response-related shorthands, i.e. JsonContent, which should suffice for now:

/**
 * @OA\Response(
 *     response="200",
 *     description="Success",
 *     @OA\JsonContent(ref=@Model(type=Article::class, groups={"light"}))
 * )
 */

In the example above, JsonContent is "unmerged" when ModelRegister is invoked, which will require some updates to that conditional logic.

That'd be great, we may want to experience it a bit first though to see how we could implement this the most efficiently, what do you think?

As for the request, there does not seem to be a defined shorthand, so we would have to do something like:

/**
 * @OA\Post(
 *     @OA\RequestBody(
 *         request="foo",
 *         description="This is a parameter",
 *         @OA\MediaType(
 *             mediaType="application/json",
 *             @OA\Schema(type="array", @OA\Items(ref=@Model(type=User::class)))
 *         )
 *     )
 * )
 */

An additional realization about RequestBody: It must be nested under an "operation".

[GuilhemN]

As for the request, there does not seem to be a defined shorthand, so we would have to do something like:

Doesn't JsonContent also work in RequestBody?

An additional realization about RequestBody: It must be nested under an "operation".

It's already the case for other annotations like @Response and we have a mechanism in SwaggerPhpDescriber to deal with that so I guess it probably only requires adding a few conditions to accept RequestBody as well.

[namoscato]

Doesn't JsonContent also work in RequestBody?

Ah yes, it looks like it should!

[alytvynov]

Good day !

Any updates for supporting OAS 3 ?
Does NelmioApiDocBundle supports the 3rd version of swagger ?

Will it work with OA annotations ?
https://github.com/zircote/swagger-php/releases/tag/3.0.0

/**
 * @OA\Info(title="My First API", version="0.1")
 */

And will it support openapi versioning in ./config/pachages/nelmio_api_doc.yaml ?

[gabrielspiteri-highlight]

@namoscato @GuilhemN were there any updates regarding the support for OpenAPI 3.0 ?

[namoscato]

@alytvynov, @gabrielspiteri-highlight – I got a decent start on this earlier in the year but unfortunately have not had a ton of time to circle back recently. The state in which I left it is a bit of a mess (i.e. with commented out code, todos, etc). Ideally, I will try to clean some of that up and document what else is left to do within the next couple of weeks.

[gabrielspiteri-highlight]

Thanks for the update.

---

From: Nick Amoscato [e-mail]
Sent: Wednesday, November 6, 2019 12:43:31 PM
To: nelmio/NelmioApiDocBundle [e-mail]
Cc: Gabriel Spiteri [e-mail]; Mention [e-mail]
Subject: Re: [nelmio/NelmioApiDocBundle] Support for OAS 3.0 (#1443)

@alytvynovhttps://github.com/alytvynov, @gabrielspiteri-highlighthttps://github.com/gabrielspiteri-highlight – I got a decent start on this earlier in the year but unfortunately have not had a ton of time to circle back recently. The state in which I left ithttps://github.com/nelmio/NelmioApiDocBundle/compare/dev...namoscato:oa-functional is a bit of a mess (i.e. with commented out code, todos, etc). Ideally, I will try to clean some of that up and document what else is left to do within the next couple of weeks.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHubhttps://github.com/nelmio/NelmioApiDocBundle/issues/1443?email_source=notifications&email_token=AKMWF2L5OVKZRCVGHIMULM3QSKUWHA5CNFSM4GIAW2E2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEDGIEEY#issuecomment-550273555, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AKMWF2JIVZM44D77W2XUEDTQSKUWHANCNFSM4GIAW2EQ.

[Ocramius]

Cc-ing @lornajane to get more attention on this by possible openapi contributors

[namoscato]

https://github.com/nelmio/NelmioApiDocBundle/pull/1555 captures my current state. Feedback is certainly welcome, and I would love some help breaking down the work that remains.

[demyan112rv]

Any news about support OpenAPI 3.0?

[adiux]

Im interested in this too

[mabzzz]

+1

[alytvynov]

+1

[Ocramius]

Folks, +1-ing on issues is very much bad manners on open source projects: if you want to see it done, step up and help.

A "+1" is a good way to annoy already busy maintainers: stop that.

[mantis]

And in terms of stepping up, someone has submitted a PR for open api 3 support int https://github.com/nelmio/NelmioApiDocBundle/pull/1623

[GuilhemN]

I'm closing this issue since https://github.com/nelmio/NelmioApiDocBundle/pull/1623 is merged.
Please give NelmioApiDocBundle v4 first beta a try and give us your feedback.