Skip to content

Commit 8f217c2

Browse files
suraj-webkulsuraj-webkul
committed
write swagger documentation
1 parent 1d424ef commit 8f217c2

File tree

11 files changed

+990
-0
lines changed

11 files changed

+990
-0
lines changed

‎composer.json

+3
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212
"Webkul\\RestApi\\": "src/"
1313
}
1414
},
15+
"require": {
16+
"darkaonline/l5-swagger": "^8.6"
17+
},
1518
"extra": {
1619
"laravel": {
1720
"providers": [

‎src/Config/l5-swagger.php

+302
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,302 @@
1+
<?php
2+
3+
return [
4+
'default' => 'default',
5+
'documentations' => [
6+
'default' => [
7+
'api' => [
8+
'title' => 'Krayin Rest API Documentation',
9+
],
10+
11+
'routes' => [
12+
/*
13+
* Route for accessing api documentation interface
14+
*/
15+
'api' => 'api/documentation',
16+
'docs' => storage_path('api-docs'),
17+
'oauth2_callback' => 'api/oauth2-callback',
18+
],
19+
'paths' => [
20+
/*
21+
* Edit to include full URL in ui for assets
22+
*/
23+
'use_absolute_path' => env('L5_SWAGGER_USE_ABSOLUTE_PATH', true),
24+
25+
/*
26+
* File name of the generated json documentation file
27+
*/
28+
'docs_json' => 'api-docs.json',
29+
30+
/*
31+
* File name of the generated YAML documentation file
32+
*/
33+
'docs_yaml' => 'api-docs.yaml',
34+
35+
/*
36+
* Set this to `json` or `yaml` to determine which documentation file to use in UI
37+
*/
38+
'format_to_use_for_docs' => env('L5_FORMAT_TO_USE_FOR_DOCS', 'json'),
39+
40+
/*
41+
* Absolute paths to directory containing the swagger annotations are stored.
42+
*/
43+
'annotations' => [
44+
base_path('vendor/krayin/rest-api/src/Docs'),
45+
],
46+
47+
],
48+
],
49+
],
50+
'defaults' => [
51+
'routes' => [
52+
/*
53+
* Route for accessing parsed swagger annotations.
54+
*/
55+
'docs' => 'docs',
56+
57+
/*
58+
* Route for Oauth2 authentication callback.
59+
*/
60+
'oauth2_callback' => 'api/oauth2-callback',
61+
62+
/*
63+
* Middleware allows to prevent unexpected access to API documentation
64+
*/
65+
'middleware' => [
66+
'api' => [],
67+
'asset' => [],
68+
'docs' => [],
69+
'oauth2_callback' => [],
70+
],
71+
72+
/*
73+
* Route Group options
74+
*/
75+
'group_options' => [],
76+
],
77+
78+
'paths' => [
79+
/*
80+
* Absolute path to location where parsed annotations will be stored
81+
*/
82+
'docs' => storage_path('api-docs'),
83+
84+
/*
85+
* Absolute path to directory where to export views
86+
*/
87+
'views' => base_path('resources/views/vendor/l5-swagger'),
88+
89+
/*
90+
* Edit to set the api's base path
91+
*/
92+
'base' => env('L5_SWAGGER_BASE_PATH', null),
93+
94+
/*
95+
* Edit to set path where swagger ui assets should be stored
96+
*/
97+
'swagger_ui_assets_path' => env('L5_SWAGGER_UI_ASSETS_PATH', 'vendor/swagger-api/swagger-ui/dist/'),
98+
99+
/*
100+
* Absolute path to directories that should be exclude from scanning
101+
* @deprecated Please use `scanOptions.exclude`
102+
* `scanOptions.exclude` overwrites this
103+
*/
104+
'excludes' => [],
105+
],
106+
107+
'scanOptions' => [
108+
/**
109+
* analyser: defaults to \OpenApi\StaticAnalyser .
110+
*
111+
* @see \OpenApi\scan
112+
*/
113+
'analyser' => null,
114+
115+
/**
116+
* analysis: defaults to a new \OpenApi\Analysis .
117+
*
118+
* @see \OpenApi\scan
119+
*/
120+
'analysis' => null,
121+
122+
/**
123+
* Custom query path processors classes.
124+
*
125+
* @link https://github.com/zircote/swagger-php/tree/master/Examples/schema-query-parameter-processor
126+
* @see \OpenApi\scan
127+
*/
128+
'processors' => [
129+
// new \App\SwaggerProcessors\SchemaQueryParameter(),
130+
],
131+
132+
/**
133+
* pattern: string $pattern File pattern(s) to scan (default: *.php) .
134+
*
135+
* @see \OpenApi\scan
136+
*/
137+
'pattern' => null,
138+
139+
/*
140+
* Absolute path to directories that should be exclude from scanning
141+
* @note This option overwrites `paths.excludes`
142+
* @see \OpenApi\scan
143+
*/
144+
'exclude' => [],
145+
146+
/*
147+
* Allows to generate specs either for OpenAPI 3.0.0 or OpenAPI 3.1.0.
148+
* By default the spec will be in version 3.0.0
149+
*/
150+
'open_api_spec_version' => env('L5_SWAGGER_OPEN_API_SPEC_VERSION', \L5Swagger\Generator::OPEN_API_DEFAULT_SPEC_VERSION),
151+
],
152+
153+
/*
154+
* API security definitions. Will be generated into documentation file.
155+
*/
156+
'securityDefinitions' => [
157+
'securitySchemes' => [
158+
/*
159+
* Examples of Security schemes
160+
*/
161+
/*
162+
'api_key_security_example' => [ // Unique name of security
163+
'type' => 'apiKey', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
164+
'description' => 'A short description for security scheme',
165+
'name' => 'api_key', // The name of the header or query parameter to be used.
166+
'in' => 'header', // The location of the API key. Valid values are "query" or "header".
167+
],
168+
'oauth2_security_example' => [ // Unique name of security
169+
'type' => 'oauth2', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
170+
'description' => 'A short description for oauth2 security scheme.',
171+
'flow' => 'implicit', // The flow used by the OAuth2 security scheme. Valid values are "implicit", "password", "application" or "accessCode".
172+
'authorizationUrl' => 'http://example.com/auth', // The authorization URL to be used for (implicit/accessCode)
173+
//'tokenUrl' => 'http://example.com/auth' // The authorization URL to be used for (password/application/accessCode)
174+
'scopes' => [
175+
'read:projects' => 'read your projects',
176+
'write:projects' => 'modify projects in your account',
177+
]
178+
],
179+
*/
180+
181+
/* Open API 3.0 support
182+
'passport' => [ // Unique name of security
183+
'type' => 'oauth2', // The type of the security scheme. Valid values are "basic", "apiKey" or "oauth2".
184+
'description' => 'Laravel passport oauth2 security.',
185+
'in' => 'header',
186+
'scheme' => 'https',
187+
'flows' => [
188+
"password" => [
189+
"authorizationUrl" => config('app.url') . '/oauth/authorize',
190+
"tokenUrl" => config('app.url') . '/oauth/token',
191+
"refreshUrl" => config('app.url') . '/token/refresh',
192+
"scopes" => []
193+
],
194+
],
195+
],
196+
*/
197+
'sanctum_admin' => [ // Unique name of security
198+
'type' => 'apiKey', // Valid values are "basic", "apiKey" or "oauth2".
199+
'description' => 'Enter token in format (Bearer <token>)',
200+
'name' => 'Authorization', // The name of the header or query parameter to be used.
201+
'in' => 'header', // The location of the API key. Valid values are "query" or "header".
202+
],
203+
],
204+
'security' => [
205+
/*
206+
* Examples of Securities
207+
*/
208+
[
209+
/*
210+
'oauth2_security_example' => [
211+
'read',
212+
'write'
213+
],
214+
215+
'passport' => []
216+
*/
217+
],
218+
],
219+
],
220+
221+
/*
222+
* Set this to `true` in development mode so that docs would be regenerated on each request
223+
* Set this to `false` to disable swagger generation on production
224+
*/
225+
'generate_always' => env('L5_SWAGGER_GENERATE_ALWAYS', false),
226+
227+
/*
228+
* Set this to `true` to generate a copy of documentation in yaml format
229+
*/
230+
'generate_yaml_copy' => env('L5_SWAGGER_GENERATE_YAML_COPY', false),
231+
232+
/*
233+
* Edit to trust the proxy's ip address - needed for AWS Load Balancer
234+
* string[]
235+
*/
236+
'proxy' => false,
237+
238+
/*
239+
* Configs plugin allows to fetch external configs instead of passing them to SwaggerUIBundle.
240+
* See more at: https://github.com/swagger-api/swagger-ui#configs-plugin
241+
*/
242+
'additional_config_url' => null,
243+
244+
/*
245+
* Apply a sort to the operation list of each API. It can be 'alpha' (sort by paths alphanumerically),
246+
* 'method' (sort by HTTP method).
247+
* Default is the order returned by the server unchanged.
248+
*/
249+
'operations_sort' => env('L5_SWAGGER_OPERATIONS_SORT', null),
250+
251+
/*
252+
* Pass the validatorUrl parameter to SwaggerUi init on the JS side.
253+
* A null value here disables validation.
254+
*/
255+
'validator_url' => null,
256+
257+
/*
258+
* Swagger UI configuration parameters
259+
*/
260+
'ui' => [
261+
'display' => [
262+
/*
263+
* Controls the default expansion setting for the operations and tags. It can be :
264+
* 'list' (expands only the tags),
265+
* 'full' (expands the tags and operations),
266+
* 'none' (expands nothing).
267+
*/
268+
'doc_expansion' => env('L5_SWAGGER_UI_DOC_EXPANSION', 'none'),
269+
270+
/**
271+
* If set, enables filtering. The top bar will show an edit box that
272+
* you can use to filter the tagged operations that are shown. Can be
273+
* Boolean to enable or disable, or a string, in which case filtering
274+
* will be enabled using that string as the filter expression. Filtering
275+
* is case-sensitive matching the filter expression anywhere inside
276+
* the tag.
277+
*/
278+
'filter' => env('L5_SWAGGER_UI_FILTERS', true), // true | false
279+
],
280+
281+
'authorization' => [
282+
/*
283+
* If set to true, it persists authorization data, and it would not be lost on browser close/refresh
284+
*/
285+
'persist_authorization' => env('L5_SWAGGER_UI_PERSIST_AUTHORIZATION', false),
286+
287+
'oauth2' => [
288+
/*
289+
* If set to true, adds PKCE to AuthorizationCodeGrant flow
290+
*/
291+
'use_pkce_with_authorization_code_grant' => false,
292+
],
293+
],
294+
],
295+
/*
296+
* Constants which can be used in annotations
297+
*/
298+
'constants' => [
299+
'APP_URL' => env('APP_URL'),
300+
],
301+
],
302+
];

‎src/Console/Commands/Install.php

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<?php
2+
3+
namespace Webkul\RestApi\Console\Commands;
4+
5+
use Illuminate\Console\Command;
6+
7+
class Install extends Command
8+
{
9+
/**
10+
* The name and signature of the console command.
11+
*
12+
* @var string
13+
*/
14+
protected $signature = 'krayin-rest-api:install';
15+
16+
/**
17+
* The console command description.
18+
*
19+
* @var string
20+
*/
21+
protected $description = 'Publish L5SwaggerServiceProvider provider, view and config files.';
22+
23+
/**
24+
* Install and configure bagisto rest api.
25+
*/
26+
public function handle()
27+
{
28+
$this->warn('🔧 Step 1: Publishing L5Swagger Provider File...');
29+
30+
$result = shell_exec('php artisan vendor:publish --tag=krayin-rest-api-swagger');
31+
32+
if ($result) {
33+
$this->info('📄 Provider file published successfully! 🚀');
34+
} else {
35+
$this->error('❌ Failed to publish the provider file. Please check the error logs.');
36+
}
37+
38+
$this->warn('🔧 Step 2: Generating L5-Swagger Docs for Admin...');
39+
40+
$result = shell_exec('php artisan l5-swagger:generate --all');
41+
42+
if ($result) {
43+
$this->info('📚 Swagger documentation generated successfully! 📘');
44+
} else {
45+
$this->error('❌ Failed to generate Swagger documentation. Please check the error logs.');
46+
}
47+
48+
$this->comment('-----------------------------');
49+
50+
$this->comment('🎉 Success! Krayin REST API has been configured successfully. Enjoy your newly documented API! 🚀✨');
51+
}
52+
}

0 commit comments

Comments
 (0)