junioalmeida/slim-framework-swagger-json-and-viewer

Gera json Swagger e visualização da documentação por meio deste mesmo json.

1.0.225 2017-10-24 15:19 UTC

This package is auto-updated.

Last update: 2022-04-29 01:14:17 UTC


README

Este código integra a biblioteca swagger-php com Slim Framework 3, disponibilizando dois recursos:

1 - JSON FILE: Geração automática do arquivo json para Swagger.

  • Rota para o json gerado automaticamente:
    [GET] /docs/json (Pode ser alterada)
  • As informações do json são obtidas por meio de Annotations, que são comentários especiais escritos em qualquer arquivo do seu projeto.
  • Pode acessar a documentação do swagger-php por aqui.
  • Veja exemplos de uso do Annotations do swagger-php.
  • Getting-started do swagger-php.
  • Escaneia por padrão a pasta /src/ (Pode ser alterado)
  • TODO: Ainda falta a implementação de alguma técnica de
    cacheamento para que não seja escaneado toda vez que a documentação
    é acessada...

2 - DOC VIEWER: Geração de link para visualização da documentação usando o swagger-ui.

  • Rota para a visualização da documentação gerada:
    [GET] /docs/view (Pode ser alterada)
  • Usa os arquivos copiados do projeto swagger.ui.
  • Links dinamicos são criados para os recursos de js e cs que estão encorporados
    nesta biblioteca.
    (Por isso não precisa se preocupar em copiar para para a pasta public)

Instalação:

1 - Este é o único código que precisa adicionar ao arquivo de dependencias do Slim Framework 3 do seu projeto para que a integração funcione.

// Configurações da integração Slim+Swagger-PHP e do Swagger-PHP 
// $app é a variavel que contem a instancia da aplicação
$container[\JunioDeAlmeida\Slim\SlimSwaggerRouteJav::class] = function ($c) use ($app) {
    return new \JunioDeAlmeida\Slim\SlimSwaggerRouteJav($app);
};
// Seteando as rotas /docs/view e /docs/json
$container[\JunioDeAlmeida\Slim\SlimSwaggerRouteJav::class]->setRouters();

Geralmente este arquivo se encontra em `/src/dependencies.php` e possui este código $container = $app->getContainer();.

2 - Confira no arquivo /public/index.php se o nome da variavel que recebe a instancia da aplicação \Slim\App chama $app :

session_start();

// Instantiate the app
$settings = require __DIR__ . '/../src/settings.php';
$app = new \Slim\App($settings);

// Set up dependencies
require __DIR__ . '/../src/dependencies.php';

Caso não seja, adapte este trecho do código: function ($c) use ($app) { em:

$container[\JunioDeAlmeida\Slim\SlimSwaggerRouteJav::class] = function ($c) use ($app) {

3 - Adicione nos settings.php e altere para que aponte para a pasta raiz onde terão as suas classes com Annotations que serão escaneadas.

return [
    'settings' => [

        // ... here another settings

        // Configuração do Swagger - gerador de documentação de api
        'swagger' => [
            // Pasta raiz que será escaneada em busca de Annotations. Um exemplo é chamado se a url não for configurada.
            'baseDir' => __DIR__ . '/../vendor/junioalmeida/slim-framework-swagger-json-and-viewer/Examples/petstore.swagger.io', // Link de exemplo
        //  'baseDir' => __DIR__ . '/../src', // Geralmente as classes do projeto fica na pasta \src\
        //  'ignoreDir' => [],
        //  'routes' => [
        //    'json' => '/docs/json',
        //    'view' => '/docs/view',
        //    'resources' => '/docs/resources/{resource}',
        //  ],
        //  'projects' => [
        //    ['name'=>'This project', 'url'=>'/docs/json'],
        //    ['name'=>'Exemplo', 'url'=>'http://petstore.swagger.io/v2/swagger.json'],
        //  ],
        //]
    ],
];

Poderá deixar o exemplo seteado temporariamente para que veja como é a documentação.