Automatic generation of API doc via Annotations or how to come to API documentation
Before writing to become tried to find something like that, and, perhaps, due to some circumstances did not find. I decided to state my vision of this issue.
Where did the idea come from? Over the past few years, I have changed 3-4 companies in which, to put it mildly, I have got noodles, thick controllers and a minimum of annotations. What is the reason for the absence of annotations? It is difficult to say, perhaps it is banal laziness or not knowing that annotations allow describing more than just the input parameters for classes / methods. And when it starts to deal with API controllers, then it's generally fun, to screw the FosRestBundle is not a problem (I’m talking about a more lazy option than writing everything and all the pens myself, although, as practice shows, the bundle is easier).
So, what am I talking about? They bundled up the bundle, described (at best) ParameterFetcher input parameters and rules. Everything seems to be ready and working, requests are running, answers are flying. But how to be when you need documentation on the API, which options I just did not see. The most damning was the text files in the folder Resource / doc - but at least served where necessary. I am sure that for the majority of those who will read this article and not close it immediately, much will already be known, but I will describe it anyway.
I will give all the examples with links to where to take and screenshots of how it works.
')
So, the bundle itself is here .
Next comes the spoiler with the NelimoApiDocBundle installation.
Then I will run purely superficially on the most simple and basic points, leaving your inquisitive mind to read and disassemble the documentation, if such a desirearises .
So, we have a simple method:
So far, this method does not stand out in any way, and we will expand it a little bit.
Now you can figure out what we wrote there like this:
On this, it seems, you can finish it, described it to a bun, and that's enough, but you still need documentation for this miracle method, and preferably informatively readable.
I will begin to describe in order:
Here, on this, probably, I will finish the superficial review of the bundle, citing as a proof the screen of what happened as a result:
PS> Corrected a link to the screen
Where did the idea come from? Over the past few years, I have changed 3-4 companies in which, to put it mildly, I have got noodles, thick controllers and a minimum of annotations. What is the reason for the absence of annotations? It is difficult to say, perhaps it is banal laziness or not knowing that annotations allow describing more than just the input parameters for classes / methods. And when it starts to deal with API controllers, then it's generally fun, to screw the FosRestBundle is not a problem (I’m talking about a more lazy option than writing everything and all the pens myself, although, as practice shows, the bundle is easier).
So, what am I talking about? They bundled up the bundle, described (at best) ParameterFetcher input parameters and rules. Everything seems to be ready and working, requests are running, answers are flying. But how to be when you need documentation on the API, which options I just did not see. The most damning was the text files in the folder Resource / doc - but at least served where necessary. I am sure that for the majority of those who will read this article and not close it immediately, much will already be known, but I will describe it anyway.
I will give all the examples with links to where to take and screenshots of how it works.
')
So, the bundle itself is here .
Next comes the spoiler with the NelimoApiDocBundle installation.
click
It is put like everything else very easily and simply through Composer:
Further, it is still easier in AppKernel.php
The most important (well, in any case with respect to the article), we prescribe the paths for the generalka itself:
require nelmio/api-doc-bundle Further, it is still easier in AppKernel.php
public function registerBundles() { //... return array( // ... new Nelmio\ApiDocBundle\NelmioApiDocBundle(), ); } The most important (well, in any case with respect to the article), we prescribe the paths for the generalka itself:
# app/config/routing.yml NelmioApiDocBundle: resource: "@NelmioApiDocBundle/Resources/config/routing.yml" prefix: /api/doc Then I will run purely superficially on the most simple and basic points, leaving your inquisitive mind to read and disassemble the documentation, if such a desire
So, we have a simple method:
click
public function getIndexAction(ParamFetcher $paramFetcher) { $view = View::create(); $result = [ 'status' => 'success', 'data' => [ 'someKey' => 'SomeValue' ] ]; $view->setData(['result' => $result]); return $view; } So far, this method does not stand out in any way, and we will expand it a little bit.
click
/** * @Get(name="_additional_name_in_route", path="/") * * @Template(engine="twig", template="HabrApiDocBundle:Default:index.html.twig") * * @QueryParam( * name="name", * requirements="\w+", * strict=true, * nullable=false, * description="Some description" * ) * * @param ParamFetcher $paramFetcher * @return View */ public function getIndexAction(ParamFetcher $paramFetcher) { $view = View::create(); $result = [ 'status' => 'success', 'data' => [ 'someKey' => 'SomeValue' ] ]; $view->setData(['result' => $result]); return $view; } Now you can figure out what we wrote there like this:
- @Get is the easiest and fastest way to override the URL for methods that respond only to 1 type of request (REST Full). This will give us the opportunity to make postIndexAction deleteIndexAction - and so on, the essence is caught.
- @Templating - to use or not, here already at will. I prefer to use, for example, to standardize responses.
- @QueryParam - the first one, using @QueryParam or @RequestParam accordingly allows you to manage the input data. For example, we have a name field, which can NOT be empty, must match the \ w + pattern, and no less important is the Description, in which you can write, why it should be entered.
On this, it seems, you can finish it, described it to a bun, and that's enough, but you still need documentation for this miracle method, and preferably informatively readable.
* @ApiDoc( * statusCodes={ * 200="Returned when successful", * 403="Returned when the user is not authorized to say hello", * 404={ * "Returned when the user is not found", * "Returned when something else is not found" * }, * }, * description = "Add here some description for this method", * requirements = { * {"name"="name", "datatype"="string", "requirements"="\w+", "description" = "description for this parameter"} * }, * cache=false, * tags = { * "stable" = "green", * "deprecated" = "#ff0000" * }, * deprecated = true, * section = "First section" * ) I will begin to describe in order:
- @ApiDoc () - naturally, at the beginning we will point to the use of the bundle itself,
- statusCodes - the purpose of this parameter can be seen from its name, but in the end it looks very nice in the documentation, tells us what and in what cases we can get as an answer.
- description - well, the captain also came, with the only difference being that now it will be visible in the documentation.
- requirements — an array of Query / Request parameters is written here with a description of their requirements, which will also be displayed in the documentation.
- tags are just something. When it is possible to put some tag on each method.
- deprecated is also a nice feature when you can mark methods that you plan to no longer use.
- section - one of the most useful additions, allows you to group in methods, even if they are in different classes.
Here, on this, probably, I will finish the superficial review of the bundle, citing as a proof the screen of what happened as a result:
Screenshot
PS> Corrected a link to the screen
Source: https://habr.com/ru/post/262927/
All Articles