nelmio / nelmioapidocbundle Goto Github PK
View Code? Open in Web Editor NEWGenerates documentation for your REST API from annotations
License: MIT License
Generates documentation for your REST API from annotations
License: MIT License
The Parser\FormTypeParser
class contains a map FormType => data type
, but it doesn't take care of custom FormType
(datepicker
, etc.).
We need a way to add new entries to this map through configuration.
Catchable Fatal Error: Argument 2 passed to Nelmio\ApiDocBundle\Parser\JmsMetadataParser::getDescription() must be an instance of JMS\SerializerBundle\Metadata\PropertyMetadata, instance of JMS\Serializer\Metadata\PropertyMetadata given, called in C:\Users\K\Documents\payrobin\webapp\vendor\nelmio\api-doc-bundle\Nelmio\ApiDocBundle\Parser\JmsMetadataParser.php on line 85 and defined in C:\Users\K\Documents\payrobin\webapp\vendor\nelmio\api-doc-bundle\Nelmio\ApiDocBundle\Parser\JmsMetadataParser.php line 172
Right now the login_check is not a controller at the application level so it's impossible to tag it with an annotation, I'm not sure if there is a way to achieve this simply.
Suppose you use an entity for your input class, it would be nice if the "required" flag on the documentation would read from the @Orm annotation. For example, I have a property like the following:
/**
* @var string $recordType
*
* @ORM\Column(name="record_type", type="integer", nullable=false)
* @JMS\Type("integer");
* @JMS\SerializedName("record_type");
* @Assert\NotBlank()
* @Assert\Choice(choices = {"distributions", "diversifications", "dividends", "oia_dividends", "restricted_stock"}, message = "Choose a valid record type")
*/
private $recordType;
It would be really nice if the "nullable" attribute was read. I could also see the "Assert\NotBlank()" doing this. If we had a way to utilize the "Assert\Choice" list that would be especially nice.
I didn't see a way to set the description for input parameters using an entity with JMS.
When using the FOSRestBundle custom actions, they all end up in the others
part of the doc as they don't have the same url than the main resource. Thus, the list and the individual item are different resources and are separated. It would be good to have sections to group actions together. This way, the other
part would be splitted into each section, staying with the other actions applied on the same objects.
And the bundle would define a default section containing all methods which don't have a section defined (which could be done at the class level once #3 is implemented)
It seems that structure returned in JMS\SerializerBundle\Metadata\ClassMetadata for property type has changed from string to array
I have following property:
/**
* @ORM\Id
* @ORM\Column(type="integer")
* @ORM\GeneratedValue(strategy="AUTO")
*
* @Type("integer")
*/
protected $customerId;
JmsMetadataParser::parse calls getMetadataForClass and gets following output:
public 'propertyMetadata' =>
array (size=18)
'customerId' =>
object(JMS\SerializerBundle\Metadata\PropertyMetadata)[433]
public 'type' =>
array (size=2)
'name' => string 'integer' (length=7)
'params' =>
array (size=0)
empty
So "type" is now an array with two keys: name and params and:
$dataType = $this->processDataType($item->type);
needs to be changed to:
$dataType = $this->processDataType($item->type['name']);
The Formatter/AbstractFormatter.php use the required field attribute. For hidden fields this is false (HTML5 hidden fields don't have and required attr). So it would be better to also check the validation rules.
If there is an unsupported field type (like choice
) in an AbstractType subclass object, the field is not included in the generated documentation.
It would be better, if the field was shown without any type specified or with some fallback type (like string).
Sandbox should use Accept
and Content-Type
headers instead of adding _format
parameter into the request. Or it should be configurable.
Otherwise form validation might fail: This form should not contain extra fields.
Right now, the various parsers set dataType
however they want, which is fine for text documentation. However, in order to implement formatters that build formats consumable by other programs, for example WSDL, Swagger, or other, this property needs to have standard values that the formatters can act on accordingly.
I've attempted to find what is causing this, but get stuck once it hits the doctrine annotation reader.
Nothing is returned from this call when it hits a auto generated FOSRestBundle generated route.
if ($annotation = $this->reader->getMethodAnnotation($method, self::ANNOTATION_CLASS)) {}
Hi
I am trying to sandbox a url which can be accessed indistinctly by GET or POST.
With SF2 I've got the option of not specify anything or specify GET|POST but in those cases NelmioApiDocBundle sends request with a Method "ANY" or "GET|POST" which causes HttpFoundation component to remove form data or even give a 405.
How can we deal with this in the sandbox mode?
it would be good to extract information about the url pattern placeholders from the route definition and if available use the @param
docblock
We shoud can choose to show or hide sandbox.
Hello,
it would be great that the ApiDoc detect the "Secure" annotation, or add an option to indicate that the api controller need an authentication and show it in the doc (with a padlock for exemple).
Thx !
Hi guys, I was trying to submit a form using the sandbox, this is the method annotations
/**
* Create a new team
*
* @Route(".{_format}", name="api_team_create")
* @Method("POST")
* @ApiDoc(
* description="Creates a new team",
* statusCodes={
* 200="Player informations are returned",
* 403="The user isn't authorized"
* },
* input="Acme\TeamBundle\Form\TeamType",
* return="Acme\TeamBundle\Entity\Team"
* )
*
* @return Renders the team just created
*/
the problem is that TeamType class has a name:
public function getName()
{
return 'team';
}
so the parameters should be built using:
team[parameter]
and not just
parameter
Shouldn't this be the correct behavior or am I missing something?
It should probably be possible to:
FormFactory#create()
this is used as root name)Hi, this is a great resource, but I'm not sure of the best way to define the properties of the underlying Class in the documentation. I'd like a section "Properties" that draws from the Exposed properties, i.e.
properties="Acme/DemoBundle/Entity/Comment",
Is there a way to do this with the Nelmio Bundle? Thanks!
Simple FormType works great, but when I add DataTransformers, docs for input becomes empty.
Hi
I was trying to use a "stable" release and I used in my composer.json
"nelmio/api-doc-bundle":"2.*@stable",
Which downloads version 2.0.0 of the bundle
But when trying to generate my api documentation I get the following error:
Call to undefined method Symfony\Component\Routing\CompiledRoute::getRequirements() in /datos/socialpoint/sp-platform-dragoncity/vendor/nelmio/api-doc-bundle/Nelmio/ApiDocBundle/Extractor/ApiDocExtractor.php on line 234
This is a line where
foreach ($route->compile()->getRequirements() as $name => $value) {
And CompiledRoute.php from SF2.1 does not have getRequirements method (Route.php, does have it, however). I am using Symfony 2.1.2.
Using composer.json pointing to dev-master works but we would like to have tagged versions
Can you confirm this issue and if confirmed get this tag to be fixed?
Best regards
This makes sense when developing and being offline.
There is in issue with the topsort in parsing JMS metadata tags that causes infinite recursion.
Example that the topsort works for:
@Type("\Acme\DemoBundle\Entity\Parent")
@Type("\Acme\DemoBundle\Entity\Child")
Example where it fails:
@Type("\Acme\DemoBundle\Entity\Parent")
@Type("\Acme\DemoBundle\Entity\Unrelated")
@Type("\Acme\DemoBundle\Entity\Child")
@Type("\Acme\DemoBundle\Entity\Parent")
What happens is that ->parse is called on the Parent, adding it to the 'parsedClasses', then Unrelated is found and parsed, however because it has no subtypes it clears the global parsedClasses, so when it then continues on with Child, it finds that it has a Parent, but has already forgotten that it has parsed this before.
Hi,
I am using Symfony 2.0.12 and I got this error after installing the bundle :
Declaration of Nelmio\ApiDocBundle\Form\Extension\DescriptionFieldTypeExtension::getDefaultOptions() must be compatible with that of Symfony\Component\Form\FormTypeExtensionInterface::getDefaultOptions()
I already have a similar problem so I think it is a compatibility problem with my version of Symfony. Is the bundle compatible with 2.0.x version of symphony or only the master ?
Or that has no relation...
Thanks
I'm working on adding a new property to the @apidoc annotation. This will let you specify 'return' in @apidoc to have have api method response structures automatically documented. This return could be specified in a couple of ways:
@ApiDoc(
return="array('user'=>MyBundle\User\UserClass)"
)
@ApiDoc(
return="MyBundle\User\UserClass"
)
//same as above, but implies something different, see explanation below
@ApiDoc(
return="MyBundle\Form\UserType"
)
This will import data for the "return" property in one of several ways:
There will most likely need to be multiple ways of parsing data object metadata, as mentioned in this issue #12
This would also take care of issue #20
The suggestions there for a ParserInterface
could be implemented to allow parsing JMS annotations, and potentially others.
After that, the "return" property can be added as a new property handled by the @apidoc annotation.
When registering form types through the form.type
DIC tag, it would be great to be able to specify the form type by its name instead of using the class name.
When using JMSSerializerBundle, it would be great to be able to see the format of the response in the doc (taken from the serializer metadata)
I'd like to add some parameter to template coming from a custom parser.
Is there any other solution than fork the repo and make my own method.html.twig ?
thanks
It could be nice to display information at the beginning of the document like conventions, dev URLs, crendentials, whatever... It should be an option btw.
Hi,
I'm getting fatal error with latest bundle version and framework version 2.1.3:
Fatal error: Call to a member function defaultValue() on a non-object in /var/www/testapp/vendor/bundles/Nelmio/ApiDocBundle/DependencyInjection/Configuration.php on line 47
When I comment out that part and provide some values in NelmioApiDocExtension.php everything works as expected.
Is this bug or i'm missing some configuration values?
Thanks!
APIs are not always fully public and you might want to generate a doc for public users and another documentation for internal use. This feature needs a bit of discussion on how to implement it, though.
There should be some way of documenting error responses for API routes. This could be done semi-automatically by scanning for @throws
docblock params, but that likely won't cover all cases. This isn't required, but would be very useful for #48.
When the application is not at the root of the domain, the path used by the sandbox is wrong. And as the path is a DIC parameter, it is impossible to provide a setup using the current request to determine the base path as it would require knowing the base path when building the container. So the default value is simply broken.
I have a method with the following annotation:
/**
* Create a new product.
* A product itself is not tied to a particular language - hence no language information is required.
*
* @Route("/products")
* @Method("POST")
* @ApiDoc(
* description="Create new product.",
* input="Frisbee\ProductBundle\Form\Type\ProductApiCreateType"
* )
*/
The ProductApiCreateType form looks like this:
<?php
namespace Frisbee\ProductBundle\Form\Type;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Collection;
class ProductApiCreateType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder->add('name');
$builder->add('categories', 'entity', array(
'class' => 'FrisbeeProductBundle:ProductCategory',
'property' => 'name',
));
}
public function setDefaultOptions(OptionsResolverInterface $resolver)
{
$collectionConstraint = new Collection(array(
'name' => new NotBlank(),
'categories' => new NotBlank()
));
$resolver->setDefaults(array(
'constraints' => $collectionConstraint
));
}
public function getName()
{
return 'product';
}
}
Whenever the documentation is generated, the following exception is thrown:
The required option "class" is missing.
in /[...]/vendor/symfony/symfony/src/Symfony/Component/OptionsResolver/OptionsResolver.php at line 278
I haven't been able to work around this - any thoughts?
On each API method, it should be possible to try it thanks to a sandbox. This is a common feature in other API doc generators. This sandbox must use its own data.
As a developer using this API, in order to know how things work, I want to:
Trying to setup a simple example with NelmioApiDocBundle. I'm guessing this is because the bundle is following Symfony2 master. Is there a way to add 2.0 support or can you point me to instructions to following 2.1 master? Thanks
Fatal error: Call to undefined method Symfony\Component\Routing\Route::addOptions() in /src/projecti/vendor/bundles/Nelmio/ApiDocBundle/Extractor/ApiDocExtractor.php on line 203
Call Stack:
0.0003 327544 1. {main}() /src/projectweb/app_dev.php:0
0.0066 817800 2. Symfony\Component\HttpKernel\Kernel->handle() /src/project/web/app_dev.php:37
0.0212 1113160 3. Symfony\Bundle\FrameworkBundle\HttpKernel->handle() /src/project/app/bootstrap.php.cache:547
0.0213 1113796 4. Symfony\Component\HttpKernel\HttpKernel->handle() /src/project/app/cache/dev/classes.php:4879
0.0213 1113796 5. Symfony\Component\HttpKernel\HttpKernel->handleRaw() /src/project/app/cache/dev/classes.php:3875
0.0799 1669508 6. call_user_func_array() /src/project/app/cache/dev/classes.php:3905
0.0799 1669640 7. Nelmio\ApiDocBundle\Controller\ApiDocController->indexAction() /src/project/app/cache/dev/classes.php:3905
0.0800 1669640 8. Nelmio\ApiDocBundle\Extractor\ApiDocExtractor->all() /src/project/vendor/bundles/Nelmio/ApiDocBundle/Controller/ApiDocController.php:21
0.2217 2097108 9. Nelmio\ApiDocBundle\Extractor\ApiDocExtractor->getData() /src/project/vendor/bundles/Nelmio/ApiDocBundle/Extractor/ApiDocExtractor.php:67
Variables in local scope (#9):
$annotation = class Nelmio\ApiDocBundle\Annotation\ApiDoc { private $filters = array ('a-filter' => array ('dataType' => 'integer'), 'another-filter' => array ('dataType' => 'string', 'pattern' => '(foo|bar) ASC|DESC')); private $formType = NULL; private $description = 'This is a description of your API method'; private $isResource = TRUE }
$comment = *uninitialized*
$comments = *uninitialized*
$docblock = '@ApiDoc(\n resource=true,\n description=\\"This is a description of your API method\\",\n filters={\n {\\"name\\"=\\"a-filter\\", \\"dataType\\"=\\"integer\\"},\n {\\"name\\"=\\"another-filter\\", \\"dataType\\"=\\"string\\", \\"pattern\\"=\\"(foo|bar) ASC|DESC\\"}\n }\n )\n \n @return \\FOS\\RestBundle\\View\\View\n /'
$line = ' /'
$matches = array ()
$method = class ReflectionMethod { public $name = 'getProfilesAction'; public $class = 'Project\\Bundle\\ApiBundle\\Controller\\ProfilesController' }
$paramDocs = array ()
$route = class Symfony\Component\Routing\Route { private $pattern = '/profiles.{_format}'; private $defaults = array ('_controller' => 'Project\\Bundle\\ApiBundle\\Controller\\ProfilesController::getProfilesAction', '_format' => 'json'); private $requirements = array ('_method' => 'GET'); private $options = array ('compiler_class' => 'Symfony\\Component\\Routing\\RouteCompiler'); private $compiled = NULL }
I'm using FOSRestBundle with JMSSerializerBundle for my API. The input isn't specified with a Form but with a Class that is annotated with JMSSerializer annotations.
Would it be possible to support this too?
Hi all,
I don't know if this Exception is a real issue but in all cases...
I upgraded Nelmio to the latest version and I had to move request_listener.enable option to false
request_listener:
enabled: false
if set to true, this errors is returned:
<abbr title="Symfony\Component\DependencyInjection\Exception\ServiceCircularReferenceException">ServiceCircularReferenceException</abbr>: Circular reference detected for service "templating", path: "nelmio_api_doc.event_listener.request -> nelmio_api_doc.formatter.html_formatter -> templating -> twig -> twig.extension.httpkernel -> http_content_renderer -> http_content_renderer.strategy.hinclude".
Could someone help me on this please?
FOSRestBundle uses PATCH for the additional methods now. But the HTML formatter does not display routes nicely when using the PATCH method (not consistent with POST, PUT, GET or DELETE)
This bundle could support Swagger-compliant JSON. This would have several benefits:
In order to do this, we need to be able to also document input/output models for api methods. The bundle already supports documenting input models via the formType
property, and there is a proposal to allow documenting return types in #47.
If these issues are taken care of, supporting Swagger JSON could be done by implementing a new SwaggerFormatter
, and adding a new controller action in ApiDocController
, which would return the necessary resources.json
spec.
Doing this :
/**
* @apidoc(
* description="Get all users",
* output="AppMyTaxi\UserBundle\Entity\User")
* @rest\View
*/
public function getUsersAction() {
...
}
Get us this error :
"
Catchable Fatal Error: Argument 2 passed to
Nelmio\ApiDocBundle\Parser\JmsMetadataParser::getDescription() must be
an instance of JMS\SerializerBundle\Metadata\PropertyMetadata, instance
of JMS\Serializer\Metadata\PropertyMetadata given, called in .../vendor/nelmio/api-doc-bundle/Nelmio/ApiDocBundle/Parser/JmsMetadataParser.php
on line 85 and defined in .../vendor/nelmio/api-doc-bundle/Nelmio/ApiDocBundle/Parser/JmsMetadataParser.php
line 172
"
I have tried with a lot of different controller, and only one is working.
I tried to find a pattern but nothing so far.
"pattern"="1000/asd/2012" => 1000/asd/2012
Say you have a form with the name "user", and a parameter called "username".
At the moment there seems to be inconsistency between the documentation generated and the content expected.
The documentation generated says that I should POST a parameter called "username", but the form expects "user[username]" to be posted.
So - the documentation should either say that the parameter should be named "user[username]", or (perhaps better), the form should look in the "username" field instead of the "user[username]" field.
Does it make sense? :-)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.