Add documentation for override Swagger docs #236

Timherlaud · 2017-08-22T08:13:04Z

Hello,
I see some issues(questions) about the modification of the swagger documentation, i did a pull request

Update

dunglas · 2017-08-22T09:51:09Z

core/swagger-decorator.md

@@ -0,0 +1,70 @@
+# Override Swagger documentation


I'll suggest to add a new documentation entry for Swagger.

I'll call the file swagger.md and the title Swagger Support.

dunglas · 2017-08-22T09:51:31Z

core/swagger-decorator.md

+# Override Swagger documentation
+
+
+Symfony allow to [decorates services](https://symfony.com/doc/current/service_container/service_decoration.html), here we need to decorate the


allows to decorate

dunglas · 2017-08-22T09:52:15Z

core/swagger-decorator.md

+ services:
+      app.swagger.swagger_decorator:
+         decorates: api_platform.swagger.normalizer.documentation
+         class: AppBundle\Swagger\SwaggerDecorator


Can you put the class name into single quotes (sometimes can cause problem to not escape it)

dunglas · 2017-08-22T09:52:39Z

core/swagger-decorator.md

+ ```
+
+```php
+<?php


Can you add a comment with the path of the .php file?

dunglas · 2017-08-22T09:52:57Z

core/swagger-decorator.md

+use Symfony\Component\Serializer\Normalizer\NormalizerInterface;
+
+/**
+ * Class SwaggerDecorator.


Useless, can be remove (or replaced by an explicit description).

dunglas · 2017-08-22T09:53:06Z

core/swagger-decorator.md

+/**
+ * Class SwaggerDecorator.
+ */
+class SwaggerDecorator implements NormalizerInterface


final (according to our CS)

dunglas · 2017-08-22T09:53:19Z

core/swagger-decorator.md

+class SwaggerDecorator implements NormalizerInterface
+{
+    /**
+     * @var NormalizerInterface


Useless, will be inferred by the IDE, can be removed.

dunglas · 2017-08-22T09:53:53Z

core/swagger-decorator.md

+
+2. In Swagger decorator you can acces to the docs
+
+the variable `docs` is an array compose by paths :


no space before the colon

dunglas · 2017-08-22T09:54:21Z

core/swagger-decorator.md

+
+`$docs['paths']['{path}']['{method}']['parameters']`
+
+for example if you want to remove all references to your path ’/foos’ in method GET in the swagger you can make in the normalize function


you can do it in the normalize method

dunglas · 2017-08-22T09:55:37Z

Thank you for handling this @tim59, it's definitely useful! What do you think about introducing a real life example (like changing the path as you do in the end of this article) instead of an abstract one? It will make it easier to understand for newcomers.

Timherlaud · 2017-08-22T11:39:34Z

@dunglas maybe something like that ?
Do you think a new section with ApiNormaliser decoration in other PR may be interesting ?

dunglas

Great! I just left a few minor comments.

dunglas · 2017-08-22T12:43:00Z

core/swagger.md

+
+## Override Swagger documentation
+
+Symfony allows to [decorate services](https://symfony.com/doc/current/service_container/service_decoration.html), here we need to decorate the


the should be removed, blank lines can be removed too

dunglas · 2017-08-22T12:44:13Z

core/swagger.md

+
+### Example
+
+In the following example, we will see how to override Swagger title and add a custom filter in `/foos` path only for the `GET` method 


the title of the Swagger documentation [...] for the GEToperation of the/foos path.

dunglas · 2017-08-22T12:45:02Z

core/swagger.md

+
+final class SwaggerDecorator implements NormalizerInterface
+{
+


Extra blank line to remove

dunglas · 2017-08-22T12:45:45Z

core/swagger.md

+        ];
+
+
+		// e.g add a custom parameter 


Can you remove one level of indentation? And e.g. (nitpicking)

dunglas · 2017-08-22T12:46:22Z

core/swagger.md

+}
+```
+
+


Extra blank line to remove

dunglas · 2017-08-22T12:46:49Z

core/swagger.md

@@ -0,0 +1,71 @@
+# Swagger support


Swagger Support (title case)

Timherlaud · 2017-08-22T13:01:03Z

@dunglas , it's update :)

Do you think a new section with ApiNormaliser decoration in other PR may be interesting ?

dunglas · 2017-08-22T13:01:41Z

Do you think a new section with ApiNormaliser decoration in other PR may be interesting ?

Yes, definitely :D

dunglas · 2017-08-22T13:02:26Z

Thank you @tim59

Timherlaud · 2017-08-22T13:06:09Z

@dunglas you're welcome, about the ApiNormaliser decorator do you have advice (Title section, new file?)

dunglas · 2017-08-22T13:50:06Z

The Serialization Process in serialization.md? We cloud explain the overall process, list the available serializers and what they do, point to the Symfony's serializer docs and add a section about decorators. WDYT?

Timherlaud · 2017-08-22T13:58:25Z

Yes i'm agree with that, I will make a PR with what i know because i'm not expert in that section :)
Thx for your help

Timherlaud and others added 4 commits August 22, 2017 09:33

Merge pull request #1 from api-platform/master

288c41e

Update

Add Swagger Decorator docs

6eadfc0

Update index.md

cb2e831

Normalize not normalise

2d511a9

This was referenced Aug 22, 2017

How to manage swagger tags? api-platform/api-platform#396

Closed

Remove the filter EXACT from the Swagger documentation ? api-platform/api-platform#387

Closed

How to set custom title / description for operations? api-platform/api-platform#395

Closed

dunglas requested changes Aug 22, 2017

View reviewed changes

Tim added 5 commits August 22, 2017 13:25

Update docs following recommandations

57be724

Update docs following recommandations

77ba643

Update docs following recommandations

0e355a2

Update docs with concrete example

71ae524

Update docs with concrete example

f008db5

dunglas requested changes Aug 22, 2017

View reviewed changes

core/swagger.md Outdated

@@ -0,0 +1,71 @@

# Swagger support

Copy link

Member

dunglas Aug 22, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Swagger Support (title case)

Update docs

d5caed3

dunglas approved these changes Aug 22, 2017

View reviewed changes

dunglas merged commit 0d0dfac into api-platform:master Aug 22, 2017

		# Override Swagger documentation


		Symfony allow to [decorates services](https://symfony.com/doc/current/service_container/service_decoration.html), here we need to decorate the

+               ```
+              ```php
+              <?php


		2. In Swagger decorator you can acces to the docs

		the variable `docs` is an array compose by paths :


		`$docs['paths']['{path}']['{method}']['parameters']`

		for example if you want to remove all references to your path ’/foos’ in method GET in the swagger you can make in the normalize function


		## Override Swagger documentation

		Symfony allows to [decorate services](https://symfony.com/doc/current/service_container/service_decoration.html), here we need to decorate the


		### Example

		In the following example, we will see how to override Swagger title and add a custom filter in `/foos` path only for the `GET` method


		final class SwaggerDecorator implements NormalizerInterface
		{

Uh oh!

Add documentation for override Swagger docs #236

Add documentation for override Swagger docs #236

Uh oh!

Conversation

Timherlaud commented Aug 22, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas commented Aug 22, 2017

Uh oh!

Timherlaud commented Aug 22, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dunglas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Timherlaud commented Aug 22, 2017

Uh oh!

dunglas commented Aug 22, 2017

Uh oh!

dunglas commented Aug 22, 2017

Uh oh!

Timherlaud commented Aug 22, 2017

Uh oh!

dunglas commented Aug 22, 2017

Uh oh!

Timherlaud commented Aug 22, 2017

Uh oh!

Uh oh!

Timherlaud commented Aug 22, 2017 •

edited

Loading