api docs via swahher

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)
     {

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)
     {

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)

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
+     * Information about line.
-     * @var \App\Model\Line
+     * @var Line
+     * @Serializer\Type(Line::class)
+     * @SWG\Property(ref=@Model(type=Line::class, groups={"Default"}))
+     *
      */
     private $line;
 
     /**
-     * Information about stop
+     * Information about stop.
-     * @var \App\Model\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()

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;

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;
 

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;

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();

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;

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;
 

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],
+        ];
+    }
+}