adding attribute examples

[natsuki-engr]

• [x] faq
• [ ] common techniques
• [ ] cookbook

there could be more example codes...

[natsuki-engr]

@DerManoMann Thanks for checking my PR! In the faq, the annotation sample is shown as an example of "dummy class". So I chose the filename "dummy_class_xx.php" - was that not appropriate?

The simplest solution to avoid this issue is to add a 'dummy' class to the docblock

Please let me know if my understanding is incorrect. 🙏

[DerManoMann]

My bad - yes, this is fine.

[DerManoMann]

I think it would be good to add a script to validate that the snippets do evaluate to the same spec... I can look into that at some point.

[DerManoMann]

One think I noticed is that the attribute examples use double quotes for string. Code style here is to use single quotes unless there is actual need to use double. Might be a pain, biut probbly good to get in. I think IDE can help with that.

[natsuki-engr]

Hi, @DerManoMann CI test tests/DocSnippetsTest::testSnippets fails on some snippets because of mismatch of operationId. I guess the snippets or test should be fixed.

For example, an error on file_upload_with_headers_at.php:

1) OpenApi\Tests\DocSnippetsTest::testSnippets with data set "file_upload_with_headers-3.0.0" (array('/workspaces/swagger-php/tests...an.php', '/workspaces/swagger-php/tests...at.php'), '3.0.0')
Snippet: $/workspaces/swagger-php/tests/../docs/snippets/guide/cookbook/file_upload_with_headers_at.php > paths > /v1/media/upload > post > operationId
Failed asserting that two strings are equal.
--- Expected
+++ Actual
@@ @@
-'6e2b268bb931464252c917c84b82cba5'
+'02d11fc2bbdec221ec8917f8a596bddd'

/workspaces/swagger-php/tests/OpenApiTestCase.php:175
/workspaces/swagger-php/tests/OpenApiTestCase.php:165
/workspaces/swagger-php/tests/OpenApiTestCase.php:165
/workspaces/swagger-php/tests/OpenApiTestCase.php:165
/workspaces/swagger-php/tests/OpenApiTestCase.php:165
/workspaces/swagger-php/tests/DocSnippetsTest.php:57

The operationId mismatch is caused by a difference in the namecepace of the copies created by DocSnippetsTest::testSnippets. Possible solutions are:

1. Modify assertSpecEquals to skip the operationId check
2. Explicitly specify the operationId value within the snippet (as in minimal_api_*.php)

However, neigher apprach seems particulary good. Do you have any better ideas?

[DerManoMann]

@natsuki-engr I did push a fix to master that disables operationId generation - that should help. Sorry, no better idea 🤷

I guess you can still put in explicit ids where it makes sense, but for the purpose of this test they are not that relevant IMO.

Nice work, btw.

[natsuki-engr]

@DerManoMann Thank you so much for fixing the test code. It seems to be working fine.

I apologize for the missing many use statements. I've added them, please check it again. I also added CS check for docs/snippets directory, and the resulting formatting changes are included in commit 66d7e95. Thanks again for your help!

[DerManoMann]

No problem. Any help is appreciated and improving the docs is always valuable.

[DerManoMann]

@natsuki-engr Deployed and looking real nice!

As a side note I noticed some examples have corresponding YAML - it wonder if adding a new tab for the generated spec would work ...