laravel-swagger-ui - GitLite

KO | EN

gitlite — search

#python #hacktoberfest #react #typescript #rust #nodejs #macos #java #windows #awesome #kubernetes #vue #mcp #open-source

laravel-swagger-ui

(★ 282)

Add Swagger UI to a Laravel application.

파일 탐색기

최종 버전 다운로드 (.zip)

- - run-linting.yml
  - run-tests.yml
- swagger-ui.php
- - index.blade.php
- - InstallCommand.php
- SwaggerFile.php
- SwaggerUiServiceProvider.php
- SwaggerUiServiceProvider.stub
- - GetEndpointToolTest.php
  - GetGeneralInfoToolTest.php
  - GetRequestBodyToolTest.php
  - GetResponseToolTest.php
  - GetSchemaToolTest.php
  - ListEndpointsToolTest.php
  - ListParametersToolTest.php
  - ListRequestBodiesToolTest.php
  - ListResponsesToolTest.php
  - ListSchemasToolTest.php
  - ListSwaggerFilesToolTest.php
- - openapi.json
  - openapi.yaml
- AuthorizationTest.php
- OpenApiRouteTest.php
- SwaggerOAuth2RedirectRouteTest.php
- SwaggerUiRouteTest.php
- TestCase.php
.editorconfig
.gitattributes
.gitignore
.php-cs-fixer.php
CHANGELOG.md
composer.json
CONTRIBUTING.md
LICENSE.md
phpcs.xml
phpunit.xml.dist
README.md
UPGRADING.md

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/wotzebra/laravel-swagger-ui

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd laravel-swagger-ui

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. PHP (Composer)

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
PHP PHP 실행 환경이 필요합니다.
Composer PHP 라이브러리 설치를 위한 패키지 매니저입니다.

composer require wotz/laravel-swagger-ui

이 명령어를 터미널에 그대로 입력해 실행하세요.

composer test

이 명령어를 터미널에 그대로 입력해 실행하세요.

composer lint

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ php -S localhost:8000 같은 내장 서버로 실행한 뒤 브라우저에서 http://localhost:8000 으로 접속해보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Laravel Swagger UI

[![Latest Version on Packagist](https://img.shields.io/packagist/v/wotz/laravel-swagger-ui.svg?style=flat-square)](https://packagist.org/packages/wotz/laravel-swagger-ui)
[![Total Downloads](https://img.shields.io/packagist/dt/wotz/laravel-swagger-ui.svg?style=flat-square)](https://packagist.org/packages/wotz/laravel-swagger-ui)

This package makes it easy to make your project's Swagger (OpenAPI v3 JSON or YAML) file accessible in a Swagger UI right in your Laravel application.

The Swagger UI will automatically use your current project environment. It will set your api's base url to the active base url. Possible oauth2 configuration, such as urls and client-id/client-secret, can also be injected in Swagger UI via the configuration file.

## Installation

You can install the package via composer:

```bash
composer require wotz/laravel-swagger-ui
```

After installing Laravel Swagger UI, publish its service provider and configuration file using the `swagger-ui:install` Artisan command.

```bash
php artisan swagger-ui:install
```

## Usage

### Customize authentication and authorization

The Swagger UI is exposed at `/swagger`. By default, you will only be able to access it in the local environment. Within your `app/Providers/SwaggerUiServiceProvider.php` file, there is a `gate` method. This authorization gate controls access to Swagger UI in non-local environments. You can modify this gate as needed to restrict access to your Swagger UI and Swagger (OpenAPI v3) file:

```php
/**
 * Register the Swagger UI gate.
 *
 * This gate determines who can access Swagger UI in non-local environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewSwaggerUI', function ($user = null) {
        return in_array(optional($user)->email, [
            //
        ]);
    });
}
```

### Customize locations of Swagger (OpenAPI v3) files

In the published `config/swagger-ui.php` file, you edit the path to the Swagger UI and the location of the Swagger (OpenAPI v3) file. By default, the package expects to find the OpenAPI file in 'resources/swagger' directory. You can also provide an url if the OpenAPI file is not present in the Laravel project itself.
This is also where you can define multiple versions for the same api.

```php
// in config/swagger-ui.php

return [
    // ...

'path' => 'swagger',

'versions' => [
        'v1' => resource_path('swagger/openapi.json')
    ],

// ...
];
```

### Customize modifications to Swagger (OpenAPI v3) files and SwaggerUI

By default the package will customize the server url and the oauth urls in the OpenAPI file to the base url of the Laravel application. This can be disabled in the config.

```php
// in config/swagger-ui.php

return [
    // ...

'modify_file' => true,

// ...
];
```

You can also set what variables that should be customizable for the server url in Swagger UI. Variable must be present with the same key (case-sensitive) in the url surrounded by curly brackets.

```php
// in config/swagger-ui.php

return [
    // ...

'server_url' => 'http://foo.bar/{Language}/api',

'server_variables' => ['Language' => ['default' => 'en']],

// ...
]
```

You can also set an oauth client ID and client secret. These values will be automatically prefilled in the authentication view in Swagger UI.

```php
// in config/swagger-ui.php

return [
    // ...

'oauth' => [
        'token_path' => 'oauth/token',
        'refresh_path' => 'oauth/token',
        'authorization_path' => 'oauth/authorize',

'client_id' => env('SWAGGER_UI_OAUTH_CLIENT_ID'),
        'client_secret' => env('SWAGGER_UI_OAUTH_CLIENT_SECRET'),
    ];

// ...
];
```

### Enable and configure MCP Server based on Swagger (OpenAPI v3) files

If you want to use the mcp server that returns info about your swagger files, then you need to install the `laravel/mcp` composer package and enable the swagger server in the config:

```php
// in config/swagger-ui.php

return [
    // ...

'mcp' => [
        'enabled' => true,
    ],

// ...
];
```

By default, the MCP server is protected by the `auth:api` middleware and the `viewSwaggerUI` gate. If you are using Laravel Passport, then you still have to enable the MCP OAuth routes by adding `Mcp::oauthRoutes()` and a Passport authorization view to your codebase.

### Testing

```bash
composer test
```

## Linting

```bash
composer lint
```

### Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

## Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

If you discover any security related issues, please email gunther.debrauwer@whoownsthezebra.be instead of using the issue tracker.

## Credits

-   [Günther Debrauwer](https://github.com/gdebrauwer)
-   [All Contributors](../../contributors)

## License

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.