From 4cb1d1ead78511f6846a23bd9c7f7f6edb423d2c Mon Sep 17 00:00:00 2001
From: Kacper Donat <kadet1090@gmail.com>
Date: Mon, 9 Dec 2019 19:31:13 +0100
Subject: [PATCH] api docs via swahher
---
.../Api/v1/DeparturesController.php | 15 ++++++++
src/Controller/Api/v1/StopsController.php | 22 +++++++-----
src/Controller/Api/v1/TracksController.php | 2 +-
src/Model/Departure.php | 35 ++++++++++++++-----
src/Model/Line.php | 21 +++++++++++
src/Model/Message.php | 5 +--
src/Model/Operator.php | 6 ++++
src/Model/Referable.php | 3 ++
src/Model/ReferableTrait.php | 9 +++--
src/Model/Track.php | 9 ++++-
.../JustReferenceSerializationSubscriber.php | 28 +++++++++++++++
11 files changed, 130 insertions(+), 25 deletions(-)
create mode 100644 src/Subscriber/JustReferenceSerializationSubscriber.php
diff --git a/src/Controller/Api/v1/DeparturesController.php b/src/Controller/Api/v1/DeparturesController.php
index 0c5213a..12eb8d4 100644
--- a/src/Controller/Api/v1/DeparturesController.php
+++ b/src/Controller/Api/v1/DeparturesController.php
@@ -16,6 +16,8 @@ use Symfony\Component\Routing\Annotation\Route;
* Class DeparturesController
*
* @Route("/departures")
+ * @SWG\Tag(name="Departures")
+ * @SWG\Parameter(ref="#/parameters/provider")
*/
class DeparturesController extends Controller
{
@@ -36,6 +38,19 @@ class DeparturesController extends Controller
/**
* @Route("/", methods={"GET"})
+ * @SWG\Response(
+ * description="Gets departures from given stops.",
+ * response=200,
+ * @SWG\Schema(type="array", @SWG\Items(ref=@Model(type=Departure::class)))
+ * )
+ *
+ * @SWG\Parameter(
+ * name="stop",
+ * description="Stop identifiers.",
+ * type="array",
+ * in="query",
+ * @SWG\Items(type="string")
+ * )
*/
public function stops(DepartureRepository $departures, StopRepository $stops, Request $request)
{
diff --git a/src/Controller/Api/v1/StopsController.php b/src/Controller/Api/v1/StopsController.php
index 1229ecb..69caaf3 100644
--- a/src/Controller/Api/v1/StopsController.php
+++ b/src/Controller/Api/v1/StopsController.php
@@ -5,6 +5,7 @@ namespace App\Controller\Api\v1;
use App\Controller\Controller;
use App\Model\Stop;
+use App\Model\Track;
use App\Model\StopGroup;
use App\Provider\StopRepository;
use App\Provider\TrackRepository;
@@ -20,7 +21,7 @@ use Symfony\Component\Routing\Annotation\Route;
* @package App\Controller
* @Route("/stops")
*
- * @SWG\Tag(name="stops")
+ * @SWG\Tag(name="Stops")
* @SWG\Parameter(ref="#/parameters/provider")
*/
class StopsController extends Controller
@@ -49,10 +50,6 @@ class StopsController extends Controller
$result = $stops->getManyById($request->query->get('id'));
break;
- case $request->query->has('name'):
- $result = $stops->findGroupsByName($request->query->get('name'));
- break;
-
default:
$result = $stops->getAllGroups();
}
@@ -79,10 +76,6 @@ class StopsController extends Controller
public function groups(Request $request, StopRepository $stops)
{
switch (true) {
- case $request->query->has('id'):
- $result = $stops->getManyById($request->query->get('id'));
- break;
-
case $request->query->has('name'):
$result = $stops->findGroupsByName($request->query->get('name'));
break;
@@ -117,6 +110,17 @@ class StopsController extends Controller
/**
* @Route("/{id}/tracks", methods={"GET"})
+ *
+ * @SWG\Response(
+ * response=200,
+ * description="Returns specific stop referenced via identificator.",
+ * @SWG\Schema(type="object", properties={
+ * @SWG\Property(property="track", type="object", ref=@Model(type=Track::class)),
+ * @SWG\Property(property="order", type="integer", minimum="0")
+ * })
+ * )
+ *
+ * @SWG\Tag(name="Tracks")
*/
public function tracks(ReferenceFactory $reference, TrackRepository $tracks, $id)
{
diff --git a/src/Controller/Api/v1/TracksController.php b/src/Controller/Api/v1/TracksController.php
index 5892c7a..069a338 100644
--- a/src/Controller/Api/v1/TracksController.php
+++ b/src/Controller/Api/v1/TracksController.php
@@ -23,7 +23,7 @@ class TracksController extends Controller
* response=200,
* description="Returns all tracks for specific provider, e.g. ZTM Gdańsk.",
* )
- * @SWG\Tag(name="tracks")
+ * @SWG\Tag(name="Tracks")
* @Route("/", methods={"GET"})
*/
public function index(Request $request, TrackRepository $repository)
diff --git a/src/Model/Departure.php b/src/Model/Departure.php
index 9a3c3d3..df1e34d 100644
--- a/src/Model/Departure.php
+++ b/src/Model/Departure.php
@@ -4,44 +4,57 @@ namespace App\Model;
use Carbon\Carbon;
use JMS\Serializer\Annotation as Serializer;
+use Nelmio\ApiDocBundle\Annotation\Model;
+use Swagger\Annotations as SWG;
class Departure implements Fillable
{
use FillTrait;
/**
- * Information about line
- * @var \App\Model\Line
+ * Information about line.
+ * @var Line
+ * @Serializer\Type(Line::class)
+ * @SWG\Property(ref=@Model(type=Line::class, groups={"Default"}))
+ *
*/
private $line;
/**
- * Information about stop
- * @var \App\Model\Stop
+ * Information about stop.
+ * @var Stop
+ * @Serializer\Type(Stop::class)
*/
private $stop;
/**
- * Vehicle identification
+ * Vehicle identification.
* @var Vehicle|null
+ * @Serializer\Type(Vehicle::class)
*/
private $vehicle;
/**
- * Displayed destination
+ * Displayed destination.
* @var string|null
+ * @Serializer\Type("string")
+ * @SWG\Property(example="Łostowice Świętokrzyska")
*/
private $display;
/**
- * Estimated time of departure, null if case of no realtime data
+ * Estimated time of departure, null if case of no realtime data.
* @var Carbon|null
+ * @Serializer\Type("Carbon")
+ * @SWG\Property(type="string", format="date-time")
*/
private $estimated;
/**
- * Scheduled time of departure
+ * Scheduled time of departure.
* @var Carbon
+ * @Serializer\Type("Carbon")
+ * @SWG\Property(type="string", format="date-time")
*/
private $scheduled;
@@ -105,7 +118,11 @@ class Departure implements Fillable
$this->stop = $stop;
}
- /** @Serializer\VirtualProperty() */
+ /**
+ * @Serializer\VirtualProperty()
+ * @Serializer\Type("int")
+ * @SWG\Property(type="int")
+ */
public function getDelay(): ?int
{
return $this->getEstimated()
diff --git a/src/Model/Line.php b/src/Model/Line.php
index 917913b..b339218 100644
--- a/src/Model/Line.php
+++ b/src/Model/Line.php
@@ -2,6 +2,9 @@
namespace App\Model;
+use JMS\Serializer\Annotation as Serializer;
+use Nelmio\ApiDocBundle\Annotation\Model;
+use Swagger\Annotations as SWG;
use Tightenco\Collect\Support\Collection;
class Line implements Fillable, Referable
@@ -17,36 +20,54 @@ class Line implements Fillable, Referable
/**
* Line symbol, for example '10', or 'A'
+ * @Serializer\Type("string")
+ * @SWG\Property(example="10")
* @var string
*/
private $symbol;
/**
* Line type tram, bus or whatever.
+ * @Serializer\Type("string")
+ * @SWG\Property(type="string", enum={
+ * Line::TYPE_BUS,
+ * Line::TYPE_UNKNOWN,
+ * Line::TYPE_METRO,
+ * Line::TYPE_TRAIN,
+ * Line::TYPE_TRAM,
+ * Line::TYPE_TROLLEYBUS
+ * })
* @var string
*/
private $type;
/**
* Is line considered as fast line?
+ * @Serializer\Type("bool")
* @var boolean
*/
private $fast = false;
/**
* Is line considered as night line?
+ * @Serializer\Type("bool")
* @var boolean
*/
private $night = false;
/**
* Line operator
+ * @Serializer\Type(Operator::class)
+ * @SWG\Property(ref=@Model(type=Operator::class, groups={"Identity"}))
* @var Operator
*/
private $operator;
/**
* Tracks for this line
+ * @Serializer\Type("Collection")
+ * @SWG\Property(type="array", @SWG\Items(ref=@Model(type=Track::class)))
+ * @Serializer\Groups("Full")
* @var Collection<Track>|Track[]
*/
private $tracks;
diff --git a/src/Model/Message.php b/src/Model/Message.php
index 58dfe67..082f29a 100644
--- a/src/Model/Message.php
+++ b/src/Model/Message.php
@@ -17,6 +17,7 @@ class Message implements Fillable
/**
* Message content.
* @Serializer\Type("string")
+ * @SWG\Property(example="Tram accident on Haller alley, possible delays on lines: 2, 3, 4, 5.")
* @var string
*/
private $message;
@@ -32,7 +33,7 @@ class Message implements Fillable
/**
* Message validity time span start
* @Serializer\Type("Carbon")
- * @SWG\Property(type="string")
+ * @SWG\Property(type="string", format="date-time")
* @var Carbon|null
*/
private $validFrom;
@@ -41,7 +42,7 @@ class Message implements Fillable
* Message validity time span end
* @var Carbon|null
* @Serializer\Type("Carbon")
- * @SWG\Property(type="string")
+ * @SWG\Property(type="string", format="date-time")
*/
private $validTo;
diff --git a/src/Model/Operator.php b/src/Model/Operator.php
index 2700172..c60a8d6 100644
--- a/src/Model/Operator.php
+++ b/src/Model/Operator.php
@@ -2,30 +2,36 @@
namespace App\Model;
+use JMS\Serializer\Annotation as Serializer;
+
class Operator implements Fillable, Referable
{
use FillTrait, ReferableTrait;
/**
* Describes operator name
+ * @Serializer\Type("string")
* @var string
*/
private $name;
/**
* Contact email to operator
+ * @Serializer\Type("string")
* @var string|null
*/
private $email;
/**
* URL of operators page
+ * @Serializer\Type("string")
* @var string|null
*/
private $url;
/**
* Contact phone to operator
+ * @Serializer\Type("string")
* @var string|null
*/
private $phone;
diff --git a/src/Model/Referable.php b/src/Model/Referable.php
index 81e33d7..a4af90d 100644
--- a/src/Model/Referable.php
+++ b/src/Model/Referable.php
@@ -2,6 +2,9 @@
namespace App\Model;
+use JMS\Serializer\Annotation as Serializer;
+use Swagger\Annotations as SWG;
+
interface Referable
{
public function getId();
diff --git a/src/Model/ReferableTrait.php b/src/Model/ReferableTrait.php
index a4ccaa7..70280dc 100644
--- a/src/Model/ReferableTrait.php
+++ b/src/Model/ReferableTrait.php
@@ -2,18 +2,21 @@
namespace App\Model;
-use Swagger\Annotations as SWG;
+use JMS\Serializer\Annotation as Serializer;
trait ReferableTrait
{
/**
* Identifier coming from provider service
+ * @Serializer\Type("string")
+ * @Serializer\Groups({"Default", "Identity", "Minimal"})
* @var string
- *
- * @SWG\Property(example="1045")
*/
private $id;
+ /**
+ * @return string
+ */
public function getId()
{
return $this->id;
diff --git a/src/Model/Track.php b/src/Model/Track.php
index bae46c6..bd62451 100644
--- a/src/Model/Track.php
+++ b/src/Model/Track.php
@@ -2,6 +2,8 @@
namespace App\Model;
+use JMS\Serializer\Annotation as Serializer;
+use Nelmio\ApiDocBundle\Annotation\Model;
use Swagger\Annotations as SWG;
use Tightenco\Collect\Support\Collection;
@@ -11,6 +13,8 @@ class Track implements Referable, Fillable
/**
* Line variant describing track, for example 'a'
+ * @Serializer\Type("string")
+ * @SWG\Property(example="a")
* @var string|null
*
*/
@@ -18,12 +22,14 @@ class Track implements Referable, Fillable
/**
* Track description
+ * @Serializer\Type("string")
* @var string|null
*/
private $description;
/**
* Line reference
+ * @SWG\Property(ref=@Model(type=Line::class, groups={"Default"}))
* @var Line
*/
private $line;
@@ -31,7 +37,8 @@ class Track implements Referable, Fillable
/**
* Stops in track
* @var Stop[]|Collection
- * @SWG\Property(type="Stop")
+ * @Serializer\Type("Collection")
+ * @SWG\Property(type="array", @SWG\Items(ref=@Model(type=Stop::class)))
*/
private $stops;
diff --git a/src/Subscriber/JustReferenceSerializationSubscriber.php b/src/Subscriber/JustReferenceSerializationSubscriber.php
new file mode 100644
index 0000000..35a9754
--- /dev/null
+++ b/src/Subscriber/JustReferenceSerializationSubscriber.php
@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Subscriber;
+
+use App\Model\JustReference;
+use JMS\Serializer\EventDispatcher\EventSubscriberInterface;
+use JMS\Serializer\EventDispatcher\PreSerializeEvent;
+
+class JustReferenceSerializationSubscriber implements EventSubscriberInterface
+{
+ public function onPreSerialize(PreSerializeEvent $event)
+ {
+ $object = $event->getObject();
+ $type = $event->getType();
+
+ $event->setType(get_parent_class($object), $type['params']);
+ }
+
+ /**
+ * @inheritDoc
+ */
+ public static function getSubscribedEvents()
+ {
+ return [
+ ['event' => 'serializer.pre_serialize', 'method' => 'onPreSerialize', 'interface' => JustReference::class],
+ ];
+ }
+}
\ No newline at end of file