Пример построения REST API на Swagger + Symfony

Установка

• Клонировать репозиторий:
  git clone https://github.com/Shitovdm/Swagger_REST_API.git

• Перейти в папку с проектом:
  cd ./{PATH}

• Установить Composer

• Обновить/установить зависимости:
  composer update

Запуск

• Запустить локальный веб-сервер:
  php bin/console server:run 127.0.0.1:80

Использование

• HTTP WEB https://127.0.0.1/api

Внимание! Обратить внимание на заголовок Content-Type.
По умолчанию браузер может выставить text/html, в таком случае вы получите HTTP ERROR 406.
Необходимо принудительно установить значение application/json.
Для этого советую использовать любой REST клиент (Например Insomnia).

Это демо вариант реалиации REST API, в данной версии реализовано 3 следующих роута:

Method	HTTP request	Description
directService	GET /api/service/direct	Service type - direct
electronicService	GET /api/service/electronic	Service type - electronic
infoService	GET /api/service/info	Service information

Разработка

Инструкция от Swagger

Установка Symfony

Актуальная версия фреймворка на момент написания 3.4.

composer create-project symfony/framework-standard-edition

Установка Swagger

Актуальная версия на момент написания 2.
Возможна установка после добавления сгенерированного кода API.

Требуется версия PHP >= 5.4.0

• Установить Composer
• Добавить зависимость в composer.json:

{
    "repositories": [{
        "type": "path",
        "url": "src/Swagger/Server/"
    }]
}

• Затем запустить:

composer require swagger/server-bundle:dev-master

Добавление сгенерированного кода API

• Создать структуру ./scr/Swagger/Server/
• Поместить туда файлы сренерированного бандла.
• Добавить бандл Swagger в AppKernel( {PROJECT_ROOT} -> app/AppKernel.php ):

<?php
public function registerBundles()
{
    $bundles = array(
        // ...
        new Swagger\Server\SwaggerServerBundle(),
        // ...
    );
}

• Добавить роутинг Swagger в {PROJECT_ROOT} -> app/config/routing.yml:

swagger_server:
    resource: "@SwaggerServerBundle/Resources/config/routing.yml"

Реализация интерфейсов API

Автоматически сгенерированная инструкция

• Создать новый бандл AppBundle (если не создан)

• Добавить в каталог нового бандла AppBundle:
  {PROJECT_ROOT} -> src/AppBundle/Resources/services.yml

services:
    appbundle.api.service:
        class: AppBundle\Api\ServiceApi
        tags:
            - { name: "swagger_server.api", api: "service" }

{PROJECT_ROOT} -> src/AppBundle/Api/ServiceApiInterface.php

<?php
namespace AppBundle\Api;

use Symfony\Component\HttpFoundation\File\UploadedFile;
use Swagger\Server\Model\ApiResponse;
use Swagger\Server\Model\Service;
use Swagger\Server\Api\ServiceApiInterface;

class ServiceApi implements ServiceApiInterface // An interface is autogenerated
{
    
    public function infoService(&$responseCode, array &$responseHeaders)
    {
        // Implement the operation ...
    }

    // ...
    
}

• Зарегистрировать привязку в {PROJECT_ROOT} -> \app\config\config.yml

imports:
    - { resource: ../../src/AppBundle/Resources/config/services.yml }

Resources:

http://editor.swagger.io/ - Swagger Editor.
https://github.com/swagger-api - Swagger API.
https://github.com/symfony/symfony - Symfony PHP framefork.
https://github.com/getinsomnia/insomnia - Insomnia REST client.