kylefang/scribe
1
0
Fork 0
mirror of https://github.com/ambieco/scribe.git synced 2026-04-13 22:38:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

Separate endpoint group anem frmo group description and key by group name. Fixes #535

Browse Source
This commit is contained in:
shalvah
2019-08-25 21:23:11 +01:00
parent f691f9eb66
commit abb7ef5b60
9 changed files with 74 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
resources/views/documentarian.blade.php
View File

@@ -5,10 +5,12 @@
{!! $infoText !!}
<!-- END_INFO -->
{!! $prependMd !!}
@foreach($parsedRoutes as $group => $routes)
@if($group)
#{!! $group !!}
@foreach($parsedRoutes as $groupName => $routes)
@if($groupName)
#{!! $groupName !!}
@endif
{{-- We pick the first non-empty description we see. --}}
{!! array_first($routes, function ($route) { return $route['groupDescription'] !== ''; })['groupDescription'] ?? '' !!}
@foreach($routes as $parsedRoute)
@if($writeCompareFile === true)
{!! $parsedRoute['output'] !!}

4
src/Commands/GenerateDocumentation.php
View File

@@ -82,10 +82,10 @@ class GenerateDocumentation extends Command
$generator = new Generator($this->docConfig);
$parsedRoutes = $this->processRoutes($generator, $routes);
$parsedRoutes = collect($parsedRoutes)->groupBy('group')
$parsedRoutes = collect($parsedRoutes)->groupBy('groupName')
->sortBy(static function ($group) {
/* @var $group Collection */
return $group->first()['group'];
return $group->first()['groupName'];
}, SORT_NATURAL);
$this->writeMarkdown($parsedRoutes);

21
src/Tools/Generator.php
View File

@@ -57,7 +57,8 @@ class Generator
$controller = new ReflectionClass($class);
$method = $controller->getMethod($method);
$routeGroup = $this->getRouteGroup($controller, $method);
list($routeGroupName, $routeGroupDescription) = $this->getRouteGroup($controller, $method);
$docBlock = $this->parseDocBlock($method);
$bodyParameters = $this->getBodyParameters($method, $docBlock['tags']);
$queryParameters = $this->getQueryParameters($method, $docBlock['tags']);
@@ -69,7 +70,8 @@ class Generator
$parsedRoute = [
'id' => md5($this->getUri($route).':'.implode($this->getMethods($route))),
'group' => $routeGroup,
'groupName' => $routeGroupName,
'groupDescription' => $routeGroupDescription,
'title' => $docBlock['short'],
'description' => $docBlock['long'],
'methods' => $this->getMethods($route),
@@ -271,7 +273,7 @@ class Generator
* @param ReflectionClass $controller
* @param ReflectionMethod $method
*
* @return string
* @return array The route group name and description
*/
protected function getRouteGroup(ReflectionClass $controller, ReflectionMethod $method)
{
@@ -281,7 +283,11 @@ class Generator
$phpdoc = new DocBlock($docBlockComment);
foreach ($phpdoc->getTags() as $tag) {
if ($tag->getName() === 'group') {
return $tag->getContent();
$routeGroup = trim($tag->getContent());
$routeGroupParts = explode("\n", $tag->getContent());
$routeGroupName = array_shift($routeGroupParts);
$routeGroupDescription = implode("\n", $routeGroupParts);
return [$routeGroupName, $routeGroupDescription];
}
}
}
@@ -291,12 +297,15 @@ class Generator
$phpdoc = new DocBlock($docBlockComment);
foreach ($phpdoc->getTags() as $tag) {
if ($tag->getName() === 'group') {
return $tag->getContent();
$routeGroupParts = explode("\n", $tag->getContent());
$routeGroupName = array_shift($routeGroupParts);
$routeGroupDescription = implode("\n", $routeGroupParts);
return [$routeGroupName, $routeGroupDescription];
}
}
}
return $this->config->get(('default_group'));
return [$this->config->get(('default_group')), ''];
}
private function normalizeParameterType($type)

44
tests/Fixtures/TestGroupController.php Normal file
View File

@@ -0,0 +1,44 @@
<?php
namespace Mpociot\ApiDoc\Tests\Fixtures;
/**
* @group 1. Group 1
*
* Group 1 APIs
*/
class TestGroupController
{
/**
* Some endpoint.
*
* By default, this is in Group 1.
*/
public function action1()
{
}
/**
* Another endpoint
*
* Here we specify a group. This is also in Group 1.
*
* @group 1. Group 1
*/
public function action1b()
{
}
/**
* @group 2. Group 2
*/
public function action2()
{
}
/** @group 10. Group 10 */
public function action10()
{
}
}

21
tests/Fixtures/TestNaturalSortController.php
View File

@@ -1,21 +0,0 @@
<?php
namespace Mpociot\ApiDoc\Tests\Fixtures;
class TestNaturalSortController
{
/** @group 1. Group 1 */
public function action1()
{
}
/** @group 2. Group 2 */
public function action2()
{
}
/** @group 10. Group 10 */
public function action10()
{
}
}

2
tests/Fixtures/index.md
View File

@@ -21,6 +21,8 @@ Welcome to the generated API reference.
<!-- END_INFO -->
#Group A
<!-- START_264ee15c728df32e7ca6eedce5e42dcb -->
## Example title.

2
tests/Fixtures/partial_resource_index.md
View File

@@ -21,6 +21,8 @@ Welcome to the generated API reference.
<!-- END_INFO -->
#general
<!-- START_fc1e4f6a697e3c48257de845299b71d5 -->
## Display a listing of the resource.

2
tests/Fixtures/resource_index.md
View File

@@ -21,6 +21,8 @@ Welcome to the generated API reference.
<!-- END_INFO -->
#general
<!-- START_fc1e4f6a697e3c48257de845299b71d5 -->
## Display a listing of the resource.

4
tests/Unit/GeneratorTestCase.php
View File

@@ -214,7 +214,7 @@ abstract class GeneratorTestCase extends TestCase
public function can_parse_route_group()
{
$route = $this->createRoute('GET', '/api/test', 'dummy');
$routeGroup = $this->generator->processRoute($route)['group'];
$routeGroup = $this->generator->processRoute($route)['groupName'];
$this->assertSame('Group A', $routeGroup);
}
@@ -223,7 +223,7 @@ abstract class GeneratorTestCase extends TestCase
public function method_can_override_controller_group()
{
$route = $this->createRoute('GET', '/api/test', 'withGroupOverride');
$routeGroup = $this->generator->processRoute($route)['group'];
$routeGroup = $this->generator->processRoute($route)['groupName'];
$this->assertSame('Group B', $routeGroup);
}