php + Swagger 설치방법

(CentOS) php + Swagger 설치방법

0. Swagger UI를 설치할 서버의 프로젝트 폴더에 Swagger ui를 설치한다.
git pull https://github.com/swagger-api/swagger-ui.git

1. 만약 서버에 composer가 설치되어 있지 않다면 설치해야 한다.

//Composer 설치 스크립트를 다운로드.
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

//다운로드된 스크립트의 해시를 검증하여 정상인지 확인.
php -r "if (hash_file('sha384', 'composer-setup.php') === 'a5c698ffe4b8e2b78d36471be3b5c3c5b570e2e7743679b9f774e6962c1d6dfb') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;" 

//스크립트를 실행하여 Composer를 설치.
php composer-setup.php

//더 이상 필요 없는 설치 스크립트를 삭제.
php -r "unlink('composer-setup.php');"

2. composer를 이용하여 zircote/swagger-php 설치
(project/swagger ui가 설치되어 있는 프로젝트 폴더에서)
composer require zircote/swagger-php

3. Swagger ui를 사용하기 전 annotaion이 필요하므로 doctrine/annotations 설치
(project/swagger ui가 설치되어 있는 프로젝트 폴더에서)
composer require doctrine/annotations

4. 프로젝트 폴더에서 swagger를 볼 수 있는 index.php 파일을 만들고 
(ex: touch /project/api/document/index.php)
swagger-ui/index.html 내용을 그대로 붙여넣는다.
html파일 내부에 있는 js, css파일의 경로를 확인하여 넣어준다.

5. index.php 파일이 만들어진 위치에 api.php 파일을 만들고 
아래의 내용을 넣는다.

<?php
require("../../vendor/autoload.php"); //zircote/swagger-php를 설치하여 생긴 vendor폴더 찾기

$openapi = \OpenApi\Generator::scan([$_SERVER['DOCUMENT_ROOT'].'project']); //scan할 프로젝트 폴더의 경로

header('Content-Type: application/json');
echo $openapi->toJson();

6. 사용하려면 서버 요청 페이지에 
swagger ui용 주석을 달아서 인식시킨다.

 

 

/////////////////////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////////////////////

// 작은 프로젝트이며, 작고 가벼운 프레임워크나 CMD를 통해 서비스를 제공한다. 하는 경우에는 아래와 같이

수동으로 만드는 방법이 있다. 이게 더 쉽고 빠른거 같음..

1)  https://github.com/swagger-api/swagger-ui 해당 파일을 다운받는다.

2) ./swagger-ui-master/dist 폴더가 기본적인 Swagger Ui페이지를 제공해준다.

3) dist폴더 내의 swagger-initializer.js 파일 내부의 

  window.ui = SwaggerUIBundle({
    url: "http://domain.com/where/is/file.yaml",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });

url부분을 만들고자 하는 yaml세팅으로 바꾸어준다. 
이게 훨씬 간단하고 수정이 간편한 거 같음.
하지만 프로젝트가 크고 요청하는 API수가 많다면 이 방법이 훨씬 오래 걸릴 수 있다.
대강 yaml 파일을 꾸며보자면 다음과 같다.

---
openapi: 3.0.0
info:
  title: 테스트 API
  description: |
    해당 페이지는 테스트 API 명세페이지
#  termsOfService: http://swagger.io/terms/
#  contact:
#    email: apiteam@swagger.io
#  license:
#    name: Apache 2.0
#    url: http://www.apache.org/licenses/LICENSE-2.0.html
#  version: 1.0.0
#externalDocs:
#  description: Find out more about Swagger
#  url: http://swagger.io
servers:
- url: https://marketdev.wowpos.kr/api
  description: 테스트 API
tags:
- name: v1
  description: 테스트 API 설명
  externalDocs:
    description: Find out more
    url: http://swagger.io

paths:
  /submit:
    post:
      tags:
      - dev_v1
      summary: 테스트하기
      operationId: submit
      requestBody:
        $ref: '#/components/requestBodies/info'
      responses:
        "405":
          description: Invalid input
  
components:
  schemas:
    info:
      type: object
      properties:
        idx:
          type: integer
          description: 인덱스
        title:
          type: string
          description: 제목
      xml:
        name: info

    Response:
      type: object
      properties:
        res_cd:
          type: integer
          description: 결과코드 (정상:200,전송에러:400,서버에러:500)
        res_msg:
          type: string
          description: 결과메시지
        ads_data:
          type: string
          description: 전송광고 데이터
    
  requestBodies:
    info:
      description: Request Body 정보에 대한 설명.
      content:
       multipart/form-data:
          schema:
            $ref: '#/components/schemas/info'
#        application/xml:
#          schema:
#            $ref: '#/components/schemas/info'
#  application/json:
#          schema:
#            $ref: '#/components/schemas/info'
      required: true
#    UserArray:
#      description: List of user object
#      content:
#        application/json:
#          schema:
#            type: array
#            items:
#              $ref: '#/components/schemas/User'
#      required: true
  securitySchemes:
#    petstore_auth:
#      type: oauth2
#      flows:
#        implicit:
#          authorizationUrl: http://petstore.swagger.io/oauth/dialog
#          scopes:
#            write:pets: modify pets in your account
#            read:pets: read your pets
    api_key:
      type: apiKey
      name: api_key
      in: header