mirror of
https://github.com/retailcrm/NelmioApiDocBundle.git
synced 2025-02-02 15:51:48 +03:00
238 lines
7.1 KiB
ReStructuredText
238 lines
7.1 KiB
ReStructuredText
Frequently Asked Questions (FAQ)
|
|
================================
|
|
|
|
Sharing parameter configuration
|
|
-------------------------------
|
|
|
|
Q: I use the same value in multiple endpoints. How can I avoid duplicating the descriptions?
|
|
|
|
A: You can configure ``schemas`` in the nelmio_api_doc configuration and then reference them:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# config/nelmio_api_doc.yaml
|
|
nelmio_api_doc:
|
|
documentation:
|
|
components:
|
|
schemas:
|
|
NelmioImageList:
|
|
description: "Response for some queries"
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
example: 42
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ImageMetadata"
|
|
|
|
.. code-block:: php
|
|
|
|
// src/App/Controller/NelmioController.php
|
|
|
|
/**
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="List of image definitions",
|
|
* @OA\JsonContent(
|
|
* ref="#/components/schemas/NelmioImageList",
|
|
* )
|
|
*/
|
|
|
|
Optional Path Parameters
|
|
------------------------
|
|
|
|
Q: I have a controller with an optional path parameter. In swagger-ui, the parameter is required - can I make it
|
|
optional? The controller might look like this::
|
|
|
|
/**
|
|
* Get all user meta or metadata for a specific field.
|
|
*
|
|
* @Route("/{user}/meta/{metaName}",
|
|
* methods={"GET"},
|
|
* name="get_user_metadata"
|
|
* )
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="Json object with all user meta data or a json string with the value of the requested field"
|
|
* )
|
|
*/
|
|
public function getAction(string $user, string $metaName = null)
|
|
{
|
|
...
|
|
}
|
|
|
|
A: Optional path parameters are not supported by the OpenAPI specification. The solution to this is to define two
|
|
separate actions in your controller. For example::
|
|
|
|
/**
|
|
* Get all user meta data.
|
|
*
|
|
* @Route("/{user}/meta",
|
|
* methods={"GET"},
|
|
* name="get_user_metadata"
|
|
* )
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="Json hashmap with all user meta data",
|
|
* @OA\JsonContent(@OA\Schema(
|
|
* type="object",
|
|
* example={"foo": "bar", "hello": "world"}
|
|
* ))
|
|
* )
|
|
*/
|
|
public function cgetAction(string $user)
|
|
{
|
|
return $this->getAction($user, null);
|
|
}
|
|
|
|
/**
|
|
* Get user meta for a specific field.
|
|
*
|
|
* @Route("/{user}/meta/{metaName}",
|
|
* methods={"GET"},
|
|
* name="get_user_metadata_single"
|
|
* )
|
|
*
|
|
* @OA\Response(
|
|
* response=200,
|
|
* description="A json string with the value of the requested field",
|
|
* @OA\JsonContent(@OA\Schema(
|
|
* type="string"
|
|
* ))
|
|
* )
|
|
*/
|
|
public function getAction(string $user, string $metaName = null)
|
|
{
|
|
...
|
|
}
|
|
|
|
The first action is redundant for Symfony, but adds all the relevant documentation for the OpenAPI specification.
|
|
|
|
Asset files not loaded
|
|
----------------------
|
|
|
|
Q: How do I fix 404 or 406 HTTP status on NelmioApiDocBundle assets files (css, js, images)?
|
|
|
|
A: The assets normally are installed by composer if any command event (usually ``post-install-cmd`` or
|
|
``post-update-cmd``) triggers the ``ScriptHandler::installAssets`` script.
|
|
If you have not set up this script, you can manually execute this command:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ php bin/console assets:install --symlink
|
|
|
|
Re-add Google Fonts
|
|
-------------------
|
|
|
|
Q: How can I change the font for the UI?
|
|
|
|
A: We removed the google fonts in 3.3 to avoid the external request for GDPR reasons. To change the font, you can :doc:`customize the template <customization>` to add this style information:
|
|
|
|
.. code-block:: twig
|
|
|
|
{# templates/bundles/NelmioApiDocBundle/SwaggerUi/index.html.twig #}
|
|
{#
|
|
To avoid a "reached nested level" error an exclamation mark `!` has to be added
|
|
See https://symfony.com/blog/new-in-symfony-3-4-improved-the-overriding-of-templates
|
|
#}
|
|
{% extends '@!NelmioApiDoc/SwaggerUi/index.html.twig' %}
|
|
|
|
{% block stylesheets %}
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
|
|
{{ parent() }}
|
|
<style type="text/css" rel="stylesheet">
|
|
#formats {
|
|
font-family: Open Sans,sans-serif;
|
|
}
|
|
|
|
.swagger-ui .opblock-tag,
|
|
.swagger-ui .opblock .opblock-section-header label,
|
|
.swagger-ui .opblock .opblock-section-header h4,
|
|
.swagger-ui .opblock .opblock-summary-method,
|
|
.swagger-ui .tab li,
|
|
.swagger-ui .scheme-container .schemes>label,
|
|
.swagger-ui .loading-container .loading:after,
|
|
.swagger-ui .btn,
|
|
.swagger-ui .btn.cancel,
|
|
.swagger-ui select,
|
|
.swagger-ui label,
|
|
.swagger-ui .dialog-ux .modal-ux-content h4,
|
|
.swagger-ui .dialog-ux .modal-ux-header h3,
|
|
.swagger-ui section.models h4,
|
|
.swagger-ui section.models h5,
|
|
.swagger-ui .model-title,
|
|
.swagger-ui .parameter__name,
|
|
.swagger-ui .topbar a,
|
|
.swagger-ui .topbar .download-url-wrapper .download-url-button,
|
|
.swagger-ui .info .title small pre,
|
|
.swagger-ui .scopes h2,
|
|
.swagger-ui .errors-wrapper hgroup h4 {
|
|
font-family: Open Sans,sans-serif!important;
|
|
}
|
|
</style>
|
|
{% endblock stylesheets %}
|
|
|
|
Endpoints grouping
|
|
------------------
|
|
|
|
Q: Areas feature doesn't fit my needs. So how can I group similar endpoints of one or more controllers in a separate section in the documentation?
|
|
|
|
A: Use ``@OA\Tag`` annotation.
|
|
|
|
.. code-block:: php
|
|
|
|
/**
|
|
* Class BookmarkController
|
|
*
|
|
* @OA\Tag(name="Bookmarks")
|
|
*/
|
|
class BookmarkController extends AbstractFOSRestController implements ContextPresetInterface
|
|
{
|
|
// ...
|
|
}
|
|
|
|
Disable Default Section
|
|
-----------------------
|
|
|
|
Q: I don't want to render the "default" section, how do I do that?
|
|
|
|
A: Use ``disable_default_routes`` config in your area.
|
|
|
|
.. code-block:: yaml
|
|
|
|
nelmio_api_doc:
|
|
areas:
|
|
default:
|
|
disable_default_routes: true
|
|
|
|
Overriding a Form or Plain PHP Object Schema Type
|
|
-------------------------------------------------
|
|
|
|
Q: I'd like to define a PHP object or form with a type other any ``object``, how
|
|
do I do that?
|
|
|
|
A: By using the ``@OA\Schema`` annotation or attribute with a ``type`` or ``ref``.
|
|
Note, however, that a ``type="object"`` will still read all a models properties.
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
use OpenApi\Annotations as OA;
|
|
use Nelmio\ApiDocBundle\Annotation\Model;
|
|
|
|
/**
|
|
* @OA\Schema(type="array", @OA\Items(ref=@Model(type=SomeEntity::class)))
|
|
*
|
|
* or define a `ref`:
|
|
* @OA\Schema(ref="#/components/schemas/SomeRef")
|
|
*/
|
|
class SomeCollection implements \IteratorAggregate
|
|
{
|
|
// ...
|
|
}
|
|
|