Skip to content

Commit fcbc6bc

Browse files
iamsaintsamdark
iamsaint
and
samdark
authored
Add Swagger UI and OpenAPI annotations
Co-authored-by: Alexander Makarov <sam@rmcreative.ru>
1 parent 3f23749 commit fcbc6bc

8 files changed

Lines changed: 144 additions & 0 deletions

File tree

‎composer.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@
6363
"yiisoft/yii-debug": "^3.0@dev",
6464
"yiisoft/yii-event": "^3.0@dev",
6565
"yiisoft/yii-web": "^3.0@dev",
66+
"yiisoft/yii-swagger": "^3.0@dev",
6667
"yiisoft/user": "^3.0@dev"
6768
},
6869
"autoload": {

‎config/params.php‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
use Cycle\Schema\Generator;
66
use Spiral\Database\Driver\SQLite\SQLiteDriver;
7+
use Yiisoft\Assets\AssetManager;
8+
use Yiisoft\Factory\Definitions\Reference;
79
use Yiisoft\Yii\Cycle\Schema\Provider\FromConveyorSchemaProvider;
810
use Yiisoft\Yii\Cycle\Schema\Provider\SimpleCacheSchemaProvider;
911

@@ -19,8 +21,17 @@
1921
'@src' => '@root/src',
2022
'@data' => '@root/data',
2123
'@tests' => '@root/tests',
24+
'@views' => '@root/views',
25+
'@assets' => '@public/assets',
26+
'@assetsUrl' => '@baseUrl/assets',
2227
],
2328
],
29+
'yiisoft/view' => [
30+
'basePath' => '@views',
31+
'defaultParameters' => [
32+
'assetManager' => Reference::to(AssetManager::class),
33+
]
34+
],
2435
'yiisoft/yii-cycle' => [
2536
'dbal' => [
2637
'default' => 'default',

‎config/routes.php‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,12 @@
77
use App\Controller\SiteController;
88
use App\Controller\UserController;
99
use Yiisoft\Auth\Middleware\Authentication;
10+
use Yiisoft\DataResponse\Middleware\FormatDataResponseAsHtml;
11+
use Yiisoft\DataResponse\Middleware\FormatDataResponseAsJson;
12+
use Yiisoft\Router\Group;
1013
use Yiisoft\Router\Route;
14+
use Yiisoft\Swagger\Middleware\SwaggerJson;
15+
use Yiisoft\Swagger\Middleware\SwaggerUi;
1116

1217
return [
1318
Route::get('/', [SiteController::class, 'index'])
@@ -40,4 +45,28 @@
4045

4146
Route::post('/logout/', [AuthController::class, 'logout'])
4247
->name('logout'),
48+
49+
// Swagger routes
50+
Group::create(
51+
'/swagger',
52+
[
53+
Route::get('')
54+
->addMiddleware(fn(SwaggerUi $swaggerUi) => $swaggerUi->withJsonUrl('/swagger/json-url'))
55+
->addMiddleware(FormatDataResponseAsHtml::class),
56+
Route::get('/json-url')
57+
->addMiddleware(
58+
static function (SwaggerJson $swaggerJson) {
59+
return $swaggerJson
60+
// Uncomment cache for production environment
61+
// ->withCache(3600)
62+
->withAnnotationPaths(
63+
[
64+
'@src/Controller' // Path to API controllers
65+
]
66+
);
67+
}
68+
)
69+
->addMiddleware(FormatDataResponseAsJson::class),
70+
]
71+
),
4372
];

‎public/assets/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*
2+
!.gitignore

‎src/Controller/AuthController.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@
99
use Psr\Http\Message\ResponseInterface;
1010
use Yiisoft\DataResponse\DataResponseFactoryInterface as ResponseFactory;
1111

12+
/**
13+
* @OA\Tag(
14+
* name="auth",
15+
* description="Authentication"
16+
* )
17+
*/
1218
final class AuthController
1319
{
1420
private ResponseFactory $responseFactory;
@@ -22,6 +28,15 @@ public function __construct(
2228
$this->userService = $userService;
2329
}
2430

31+
/**
32+
* @OA\Post(
33+
* tags={"auth"},
34+
* path="/auth",
35+
* summary="Authenticate by token",
36+
* description="",
37+
* @OA\Response(response="200", description="Success")
38+
* )
39+
*/
2540
public function login(AuthRequest $request): ResponseInterface
2641
{
2742
return $this->responseFactory->createResponse(
@@ -34,6 +49,15 @@ public function login(AuthRequest $request): ResponseInterface
3449
);
3550
}
3651

52+
/**
53+
* @OA\Post(
54+
* tags={"auth"},
55+
* path="/logout",
56+
* summary="Logout",
57+
* description="",
58+
* @OA\Response(response="200", description="Success")
59+
* )
60+
*/
3761
public function logout(): ResponseInterface
3862
{
3963
$this->userService->logout();

‎src/Controller/BlogController.php‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@
1616
use Psr\Http\Message\ResponseInterface as Response;
1717
use Yiisoft\DataResponse\DataResponseFactoryInterface;
1818

19+
/**
20+
* @OA\Tag(
21+
* name="blog",
22+
* description="Blog"
23+
* )
24+
*/
1925
final class BlogController
2026
{
2127
private DataResponseFactoryInterface $responseFactory;
@@ -38,6 +44,15 @@ public function __construct(
3844
$this->blogService = $blogService;
3945
}
4046

47+
/**
48+
* @OA\Get(
49+
* tags={"blog"},
50+
* path="/blog",
51+
* summary="Returns paginated blog posts",
52+
* description="",
53+
* @OA\Response(response="200", description="Success")
54+
* )
55+
*/
4156
public function index(PageRequest $request, PaginatorFormatter $paginatorFormatter): Response
4257
{
4358
$paginator = $this->blogService->getPosts($request->getPage());
@@ -54,6 +69,15 @@ public function index(PageRequest $request, PaginatorFormatter $paginatorFormatt
5469
);
5570
}
5671

72+
/**
73+
* @OA\Get(
74+
* tags={"blog"},
75+
* path="/blog/{id}",
76+
* summary="Returns a post with a given ID",
77+
* description="",
78+
* @OA\Response(response="200", description="Success")
79+
* )
80+
*/
5781
public function view(ViewPostRequest $request): Response
5882
{
5983
return $this->responseFactory->createResponse(
@@ -65,6 +89,15 @@ public function view(ViewPostRequest $request): Response
6589
);
6690
}
6791

92+
/**
93+
* @OA\Post(
94+
* tags={"blog"},
95+
* path="/blog",
96+
* summary="Creates a blog post",
97+
* description="",
98+
* @OA\Response(response="200", description="Success")
99+
* )
100+
*/
68101
public function create(EditPostRequest $postRequest): Response
69102
{
70103
$post = $this->postBuilder->build(new Post(), $postRequest);
@@ -75,6 +108,15 @@ public function create(EditPostRequest $postRequest): Response
75108
return $this->responseFactory->createResponse();
76109
}
77110

111+
/**
112+
* @OA\Put(
113+
* tags={"blog"},
114+
* path="/blog/{id}",
115+
* summary="Updates a blog post with a given ID",
116+
* description="",
117+
* @OA\Response(response="200", description="Success")
118+
* )
119+
*/
78120
public function update(EditPostRequest $postRequest): Response
79121
{
80122
$post = $this->postBuilder->build(

‎src/Controller/SiteController.php‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,19 @@
77
use Psr\Http\Message\ResponseInterface;
88
use Yiisoft\DataResponse\DataResponseFactoryInterface;
99

10+
/**
11+
* @OA\Info(title="Yii API application", version="1.0")
12+
*/
1013
class SiteController
1114
{
15+
/**
16+
* @OA\Get(
17+
* path="/",
18+
* summary="Returns info about the API",
19+
* description="",
20+
* @OA\Response(response="200", description="Success")
21+
* )
22+
*/
1223
public function index(DataResponseFactoryInterface $responseFactory): ResponseInterface
1324
{
1425
return $responseFactory->createResponse(['version' => '3.0', 'author' => 'yiisoft']);

‎src/Controller/UserController.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@
1212
use Psr\Http\Message\ServerRequestInterface;
1313
use Yiisoft\DataResponse\DataResponseFactoryInterface;
1414

15+
/**
16+
* @OA\Tag(
17+
* name="user",
18+
* description="Users"
19+
* )
20+
*/
1521
final class UserController
1622
{
1723
private DataResponseFactoryInterface $responseFactory;
@@ -28,6 +34,15 @@ public function __construct(
2834
$this->userFormatter = $userFormatter;
2935
}
3036

37+
/**
38+
* @OA\Get(
39+
* tags={"user"},
40+
* path="/users",
41+
* summary="Returns paginated users",
42+
* description="",
43+
* @OA\Response(response="200", description="Success")
44+
* )
45+
*/
3146
public function index(): ResponseInterface
3247
{
3348
$dataReader = $this->userRepository->findAllOrderByLogin();
@@ -43,6 +58,15 @@ public function index(): ResponseInterface
4358
);
4459
}
4560

61+
/**
62+
* @OA\Get(
63+
* tags={"user"},
64+
* path="/users/{id}",
65+
* summary="Returns a user with a given ID",
66+
* description="",
67+
* @OA\Response(response="200", description="Success")
68+
* )
69+
*/
4670
public function view(ServerRequestInterface $request): ResponseInterface
4771
{
4872
/**

0 commit comments

Comments
 (0)