[Laravel 5] Swagger 사용하기

1. swagger은 api 문서 정리를 위한 도구이다.

2. 참고로 필자는 무료 라라벨 어드민 페이지를 쓰고, php 7 환경이다.

(https://startlaravel.com/themes/sb-admin-laravel-5/)

2. swagger-php를 설치한다. cmd 실행 후, 프로젝트 경로로 가서, 아래 강조 표시한 부분을 입력한다.

강조 표시 부부을 입력한 뒤, 시간이 좀 지나야지 잡다한 메세지가 뜨게된다.

>> composer require zircote/swagger-php

Using version ^2.0 for zircote/swagger-php

./composer.json has been updated

Loading composer repositories with package information

Updating dependencies (including require-dev)

Package operations: 3 installs, 0 updates, 0 removals

  - Installing doctrine/lexer (v1.0.1): Loading from cache

  - Installing doctrine/annotations (v1.4.0): Downloading (100%)

  - Installing zircote/swagger-php (2.0.13): Downloading (100%)

Writing lock file

Generating autoload files

> php artisan clear-compiled

> php artisan optimize

Generating optimized class loader

>> composer global require zircote/swagger-php

Changed current directory to C:/Users/posk1/AppData/Roaming/Composer

Using version ^2.0 for zircote/swagger-php

./composer.json has been updated

Loading composer repositories with package information

Updating dependencies (including require-dev)

Package operations: 4 installs, 0 updates, 0 removals

  - Installing symfony/finder (v3.4.6): Downloading (100%)

  - Installing doctrine/lexer (v1.0.1): Loading from cache

  - Installing doctrine/annotations (v1.4.0): Loading from cache

  - Installing zircote/swagger-php (2.0.13): Loading from cache

Writing lock file

Generating autoload files

>>composer update --no-scripts

Loading composer repositories with package information

Updating dependencies (including require-dev)

Package operations: 6 installs, 46 updates, 0 removals

  - Updating vlucas/phpdotenv (v1.1.0 => v1.1.1): Downloading (100%)

      ....

  cache

  - Updating phpspec/prophecy (v1.3.1 => 1.7.5): Loading from cache

  - Updating phpunit/phpunit (4.5.0 => 4.8.36): Downloading (100%)

  - Updating phpspec/phpspec (2.1.1 => 2.5.8): Downloading (100%)

paragonie/random_compat suggests installing ext-libsodium (Provides a modern crypto API that can be used to generate random bytes.)

Writing lock file

Generating autoload files

3. localhost:8000/public/createDoc.php 처럼 접근이 가능한 파일을 하나 만든다.

* 필자는 app\Http\routes.php 에 접근하기로 했다. 아래처럼 적어주면된다.

<?php

use Swagger\Annotations as SWG;

require("../vendor/autoload.php");

$swagger = \Swagger\scan('laravel 프로젝트 경로\app\Http');

//dd($swagger);

header('Content-Type: application/json');

echo $swagger;

?>

4. routes.php에 아래오 같이 작성해준다. 그러면 나중에 그에 맞게 json을 만들어준다.

/**

 * @SWG\Info(title="My First API", version="0.1")

 */

 /**

  * @SWG\Swagger(

  *   schemes={"http"},

  *   host="example.com",

  *   basePath="/api"

  * )

  */

Route::get('/createDoc', function(){

return View::make('createDoc');

});

5. 만든 php파일에 접근하면, PEAR 가 없다고 나온다면,

http://www.geeksengine.com/article/install-pear-on-windows.html

여기에 따라서 진행한다. 영어로 아주 잘 되어 있다.

중요한것은 C:\php\pear 부분을 php.ini 에 적어주라는 부분이 있는데,

c:\php 는 php 설치한 폴더로 지정해줘야한다.

복사, 붙여넣기로 실수하지 말기 바란다.

5. 정상적으로 접속하면 json을 볼 수 있다. 그럼 정상적으로 만들어진것이다.

6. 이제 우리가 보기 편한 UI 형태로 보이도록 만들 차례이다.

7. Swagger-ui 를 수동으로 다운로드한다. 아래 url로 들어가서 우측쯤에 clone or download를 클릭 후 Download ZIP 한다.

https://github.com/swagger-api/swagger-ui

8. 다운로드한 내용에

\swagger-ui-master\dist 안에 있는 모든 파일을 복사 후,

프로젝트 경로\public\swagger 에 모두 붙여 넣어준다. swagger 폴더는 만든다.

9. 프로젝트 경로\api 폴더를 만든다.

그리고 커맨드 창(cmd)을 연다.

cd 프로젝트 경로\vendor\zircote\swagger-php\bin

으로 이동한다. (불편하다면 환경변수에 등록해서 써도 된다.)

10. 아래와 같이 명령어를 입력한다.

swagger 프로젝트 경로\app\Http -o 프로젝트경로\api

이렇게하면 프로젝트\api 에 swagger.json 파일이 만들어진다.

위에 5번에 언급한 json이 들어가 있다.

11. 이제 url을 입력해본다.

필자의 경우는

http://localhost:8000/public/swagger/index.html

으로 접속하면

이렇게 나오게된다.

12. 이제  Explore 옆에 url을 이렇게 입력한다.

http://localhost:8000/api/swagger.json

그럼 아래와 비슷한 스샷을 볼 수 있다.

dashboard는 필자가 테스트로 넣어둔것이니, 나오지 않는다.

13. 이제 Swagger 스터디해서 사용방법을 숙지하면된다.

http://zircote.com/swagger-php/

이곳을 참조해서 공부해서 잘 써먹자.