flight php swagger
v0.6.2
Swagger, PHPUnit 및 기타 유용한 유틸리티와 함께 번들로 제공되는 비행 마이크로 프레임워크입니다. 기본 프로젝트 설정, 테스트 경로 및 모델은 물론 단위 테스트용 템플릿을 포함하여 앞서 언급한 도구로 구축된 API 개발을 시작하는 데 도움이 되도록 설계되었습니다.
이 가이드에서는 현재 프로젝트에서 다음 기술을 사용 중이거나 사용할 계획이라고 가정합니다.
PHP 7.1+
작곡가
Xdebug(PHPUnit을 사용하려는 경우 필수)
먼저, PHP 7.1 이상을 사용하여 실행 중인 웹 서버(예: Apache)를 설치하고 구성했는지 확인하십시오.
composer 사용하여 프로젝트 뼈대를 다운로드하고, 필요한 모든 종속성을 설치하고, 샘플 단위 테스트를 실행하세요.
composer create-project tribeos/flight-php-swagger path/to/project
Flight는 작동하기 위해 Apache 2의 mod_rewrite 모듈에 의존하므로 먼저 a2enmod 통해 이를 활성화한 다음 서버를 다시 시작해야 합니다.
sudo a2enmod rewrite
sudo systemctl restart apache2
이후에는 다시 쓰기 규칙을 적용하기 위해 .htaccess 파일을 사용하는 것이 처음에는 금지되므로 Apache의 기본 구성 파일도 편집해야 합니다. 구성 파일은 일반적으로 /etc/apache2/apache2.conf 에 있습니다. 여기에서 /var/www 디렉터리를 참조하는 블록을 찾아 AllowOverride All 로 설정되어 있고 Require all granted 확인하세요.
<Directory /var/www/>옵션 색인 FollowSymLinksAllowOverride AllRequire 모두 허용됨 </디렉토리>
변경 사항을 저장한 후 Apache 서버를 다시 시작합니다.
여러 사이트 구성이 있거나 원하는 경우 /etc/apache2/sites-available 에서 원하는 구성 파일을 편집하여 사이트별로 다시 쓰기 규칙을 활성화할 수도 있습니다. 자세한 내용은 다음 튜토리얼을 참조하세요.
참고 : 앞서 언급한 지침에서는 Ubuntu 배포판을 사용하고 있다고 가정합니다. 다른 운영 체제를 사용하는 경우 다시 쓰기 모듈 활성화에 대한 해당 튜토리얼을 참조하십시오.
윈도우(WAMP/XAMPP)
CentOS
프로젝트와 해당 종속성을 사용하려면 특정 PHP 확장을 설치해야 합니다. 누락될 수 있는 일반적인 확장은 다음 중 일부일 수 있습니다.
| 문제 | 해결책 |
|---|---|
mbstring | sudo apt install php-mbstring |
zip 및 unzip 관련 문제 | sudo apt install zip unzip php-zip |
참고 : 이전 Apache 2 섹션과 마찬가지로 이 지침은 Ubuntu 배포판과 관련이 있습니다. 다른 운영 체제를 사용하는 경우 적절한 대체 명령을 참조하십시오.
설치가 완료되면 프로젝트에서 다음 구조를 찾을 수 있습니다.
path/to/project ├── app │ ├── models │ │ └── SampleModel.php │ ├── routes │ │ ├── FlightSetup.php │ │ └── SampleRoute.php │ └── utils │ └── Validator.php ├── config │ ├── config.php │ └── config.sample.php ├── docs ├── logs │ └── .htaccess ├── tests │ ├── build │ └── unit │ └── SampleTest.php ├── vendor ├── .gitignore ├── .htaccess ├── autoload.php ├── composer.json ├── composer.lock ├── index.php ├── LICENSE ├── phpunit.xml └── README.md
주요 프로젝트 구성 요소 요약:
app : 기본 애플리케이션 폴더
models : 요청/응답에 사용되는 모델
routes : API 경로 정의
utils : 유효성 검사기 및 로거와 같은 응용 프로그램 유틸리티
config : 구성 파일
docs : Swagger 문서 파일
logs : 로그 저장
tests : 애플리케이션 테스트 폴더
build : 양식 테스트(코드 적용 범위 등)의 결과로 컴파일된 파일
src : 테스트 소스 파일
vendor : 모든 라이브러리 및 타사 코드의 위치
autoload.php : Composer 종속성을 로드하고 다른 모든 프로젝트 파일을 포함하는 부트스트래핑 파일
index.php : API 진입점
phpunit.xml : PHPUnit 테스트 구성
프로젝트(및 Swagger 문서)와 관련된 모든 기본 구성은 config/config.php 파일 내에서 처리됩니다. 프로젝트 필요에 따라 구성 상수를 변경/추가하세요.
또 다른 중요한 파일은 API 진입점 역할을 하는 index.php 입니다. Composer 종속성을 로드하는 코드와 기타 필요한 모든 프로젝트 파일이 포함된 autoload.php 파일이 필요합니다. 또한 Flight 프레임워크를 시작합니다. 기본적으로 가져오는 파일은 모든 models , routes 및 utils 뿐만 아니라 프로젝트 구성 파일( config/config.php ), Swagger-PHP 구성 파일( docs/swagger.php ) 및 Composer의 vendor/autoload.php 입니다. 프로젝트 요구 사항에 따라 가져올 파일을 변경/추가합니다.
Flight는 RESTful 웹 API를 빠르게 생성할 수 있는 확장 가능하고 사용하기 쉬운 PHP 프레임워크입니다. 이를 통해 미들웨어 기능 및 사용자 지정 메서드를 재정의/생성하는 기능과 함께 상세하고 기능적인 API 엔드포인트를 생성할 수 있습니다.
Flight::route('GET /sample/@value', function($value) {
Flight::json([ 'sample_value' => $value ]);
}); 프로젝트의 모든 라우팅은 Flight를 통해 수행됩니다. 초기 비행 설정( FlightSetup.php )과 모든 프로젝트 경로는 routes 폴더 내에서 처리되며 필요에 따라 변경할 수 있습니다.
Flight 홈페이지의 "학습" 영역에서 Flight에 대한 광범위한 사용 문서와 예제를 확인할 수 있습니다. Flight 프레임워크 자체에 대한 자세한 내용을 보려면 해당 GitHub 저장소를 방문하세요.
routes 폴더에 경로를 생성한 후 RESTful API에 대한 OpenAPI 문서 작성 및 생성을 시작할 수 있습니다.
문서는 해당 경로 위의 DocBlocks (일명 PHP 주석 블록) 내부에 작성됩니다.
/** * @OAGet( * path="/sample/route", * 태그={"sample"}, * summary="샘플 경로.", * @OAResponse( * response=200, * Description="A 샘플 응답." * ), * security={ * {"api_key": {}} * } * )*/모든 RESTful 엔드포인트에 대해 경로, 태그, 간략한 요약, 매개변수, 기본 매개변수 값, 요청 본문, 사용 가능한 응답, 보안 인증 및 기타 다양한 옵션을 정의할 수 있습니다.
프로젝트 이름, 프로젝트 작성자, API 서버 URL, 사양 폴더 등과 같은 일반 Swagger 구성은 config/config.php 의 "Swager 구성 상수" 영역에서 찾아 구성할 수 있습니다.
프로젝트 뼈대는 Swagger 문서화에 필요한 모든 파일(PHP 설정 파일, HTML 및 CSS)을 보유하는 docs 폴더와 결합되어 제공됩니다. 브라우저를 통해 프로젝트의 루트 경로( / )로 이동하여 문서에 액세스합니다.
Swagger 일반 및 OpenAPI 표준에 대한 자세한 내용은 Swagger 공식 홈페이지를 참조하세요. PHP 구현에 관한 광범위한 사용 문서와 예제는 swagger-php 공식 홈페이지에서 확인할 수 있습니다.
프로젝트에는 HTTP 요청, 응답 및 오류 로거인 http-logger가 번들로 제공됩니다. 이 로거는 (기본적으로) 모든 들어오는 요청과 해당 응답을 탭으로 구분된 값(TSV)으로 logs/debug.log 에 기록합니다. 자세한 로거 정보 및 구성 세부 정보는 GitHub 페이지에서 확인할 수 있습니다.
로거에는 로그 파일의 위치가 필요합니다(기본적으로 config/config.php 의 상수를 통해 구성됨). 또한 로거의 기능을 완전히 활용하려면 Flight의 내부 오류 처리기를 비활성화해야 합니다(활성화된 경우 http-logger 이전에 특정 유형의 오류를 포착합니다).
/* FlightPHP의 내부 오류 로거를 비활성화합니다. */Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);/* 로거 가져오기 및 사용 */$logger = HttpLogger::get();$logger->log(); 로거는 routes/FlightSetup.php 통해 포함되며 모든 요청 후에 실행되는 Flight 미들웨어 함수 Flight::after() 내에 구성됩니다(그래서 적절한 응답을 가져올 수 있습니다). 공개 시 로거 기능과 감시할 경로를 변경할 수 있습니다.
Flight::output() Flight::output() 은 Flight::json() (JSON 응답 출력)의 기능과 사용자 정의 HTTP Logger를 결합한 사용자 정의 매핑 방법입니다. 이 메소드를 통해 전송되는 모든 API 응답은 로거에 설정된 기본 설정에 따라 자동으로 기록됩니다. 메소드는 routes/FlightSetup.php 에 정의 및 구성됩니다.
Flight 미들웨어를 사용하여 가로채지 않고 요청/응답 쌍에 대한 로깅 기능을 원할 때 유용합니다.
Flight::output() 전송될 실제 데이터( 필수 )와 응답 코드( 선택 사항 , 기본적으로 200)라는 두 가지 매개 변수를 사용합니다.
Flight::output(['sample_message' => '샘플 응답.'], 301);
Flight::validate() Flight::validate() Swagger-PHP 분석을 사용하여 예상 OpenAPI 모델 사양에 따라 전달된 요청 본문이 유효한지(모든 필수 속성 포함) 여부를 확인합니다.
모든 모델은 클래스로 선언되고 해당 속성은 공개로 설정됩니다. 모델은 app/models 에 정의되어 있으며 다음 구조를 따릅니다.
/** * @OASchema( * ) */class SampleModel {/** * @OAProperty( * 설명="요청 본문의 샘플 특성.", * example="샘플 문자열." * 필수=true * ) * @ var 문자열 */public $sample_attribute;
} 이 구체적인 예에서는 description 사용하여 모델 속성에 대한 간략한 개요를 제공하고 required 은 속성이 필수인지 여부를 결정하며 example 에서는 해당 속성에 기본값을 할당합니다. 모델 스키마에 대한 자세한 내용은 Swagger-PHP 설명서를 참조하세요.
모델 유효성 검사기 클래스는 utils/Validator.php 에 선언 및 정의되며, routes/FlightSetup.php 에 사용자 정의 매핑 Flight 메서드로 포함됩니다. 요청 본문의 유효성을 검사할 클래스와 요청 본문 자체라는 두 가지 매개 변수를 사용합니다.
Flight::validate(SampleModel::class, Flight::request()->data->getData());
추가 메서드가 호출되기 전에 API 경로 내에서 메서드를 호출해야 합니다. 모델이 유효하면 요청이 계속 실행됩니다. 모델이 검증에 실패하는 경우 400 Bad Request 응답 코드를 출력하고 요청을 종료합니다.
참고 : Flight::validate() Flight::output() 에 따라 달라지므로 프로젝트에서 사용자 정의 출력 방법을 제거하려는 경우 필요에 따라 유효성 검사기 매핑 방법을 다시 작성해야 합니다.
이 프로젝트에는 자체 테스트 외에도 코드 적용 범위 생성을 허용하는 PHP용 테스트 프레임워크인 PHPUnit이 포함되어 있습니다.
PHPUnit 테스트와 관련된 모든 설정은 phpunit.xml 에 있습니다. 설정에는 여러 가지 옵션이 있습니다.
테스트 파일의 위치 testsuites 태그 내에서 테스트를 위해 검색할 위치를 정의할 수 있습니다. 기본적으로 이는 tests/unit 입니다. 테스트 디렉토리가 정의되면( directory 태그를 통해) 테스트 실행 중에 테스트 파일이 알파벳 순서로 실행됩니다. 필요한 경우 file 태그를 통해 사용자 정의 순서로 테스트 파일을 정의할 수도 있습니다.
<테스트 스위트>
<테스트 스위트 이름="샘플-테스트-스위트">
<directory suffix="Test.php">tests/src/</directory><!-- 기본적으로 테스트 파일은 알파벳 파일 순서로 실행됩니다. 특정 실행 순서를 설정하려면 개별 테스트 파일을 정의하세요.--><!-- <file>tests/src/SampleTest.php</file> --></testsuite>
</testsuites> 테스트 적용 범위 보고서 유형 테스트가 실행된 후 다양한 유형의 테스트 보고서가 생성될 수 있습니다. 로그 유형은 logging 태그에 정의됩니다. 컴파일된 모든 테스트 파일은 기본적으로 tests/build 내부에 있습니다.
<logging><!-- 테스트 로그 유형 --><log type="testdox-html" target="tests/build/testdox.html"/>
<log type="tap" target="tests/build/report.tap"/>
<log type="junit" target="tests/build/report.junit.xml"/>
<log type="coverage-html" target="tests/build/coverage"/>
<log type="coverage-text" target="tests/build/coverage.txt"/>
<log type="coverage-clover" target="tests/build/logs/clover.xml"/>
</로깅> 코드 적용 범위에 포함/제외할 파일 코드 적용 범위 보고서에 포함(또는 제외)할 파일을 선택할 수도 있습니다. 이는 whitelist 태그 내부의 filter 태그를 통해 수행됩니다. 기본적으로 프로젝트의 PHPUnit 설정에는 models 과 routes 제외한 app 디렉터리 내의 파일이 포함됩니다(이러한 폴더에는 코드 적용 범위를 효과적으로 테스트할 수 있는 코드가 포함되어 있지 않음). 사용자 정의 포함/제외 폴더 및 파일을 정의할 수도 있습니다.
<필터>
<whitelist><!-- 코드 적용에 사용할 폴더 이름 --><directory suffix=".php">app/</directory>
<exclude><!-- 코드 적용 범위에서 제외된 파일/폴더(테스트 가능한 방법이 없는 PHP 파일) 프로젝트 요구에 따라 편집하세요. --><directory suffix=".php">앱/모델</directory>
<directory suffix=".php">앱/경로</directory>
</제외>
</화이트리스트>
</filter> 모든 단위 테스트는 기본적으로 tests/unit 디렉터리 내에 작성되어야 합니다. 테스트 파일 이름은 Test.php 로 끝나야 PHPUnit( phpunit.xml 에 정의된 대로)에서 검색할 수 있습니다(예: SampleTest.php ).
테스트 클래스는 TestCase 클래스를 확장하여 정의되며, 다양한 테스트 메소드를 포함할 수 있습니다. 테스트 이름을 지정할 때 다음 규칙을 사용할 수 있습니다. test + 카멜 표기법으로 테스트에 대한 설명(예: testThisIsASampleTest ). 이를 통해 테스트 실행 중에 테스트 사례 이름을 설명 문장으로 변환하여 개발자에게 테스트 수행 작업에 대한 추가 개요를 제공할 수 있습니다.
/* 테스트/단위/SampleTest.php */<?phpuse PHPUnitFrameworkTestCase;class SampleTest 확장 TestCase {public function testThisIsASampleTest() {$this->assertTrue(true);
}
} 모든 테스트를 실행하려면 프로젝트 루트 디렉터리 내에서 vendor/bin/phpunit --testdox 실행하세요.
root@ubuntu:/path/to/project$ Vendor/bin/phpunit --testdox Sebastian Bergmann 및 기여자가 만든 PHPUnit 7.5.16. 견본 샘플 테스트입니다
단일 테스트 파일만 실행하려면 해당 경로를 제공하십시오: vendor/bin/phpunit --testdox tests/unit/SampleTest.php
--testdox 플래그는 선택 사항이지만 권장됩니다. 위 섹션에서 설명한 대로 이름을 기반으로 테스트에 대한 설명 문장을 생성하여 테스트 내부에서 진행되는 작업을 더 쉽게 이해할 수 있기 때문입니다.
테스트를 실행한 후 tests/build/coverage 디렉터리 내에 코드 커버리지 보고서가 생성되며, 브라우저를 통해 이 경로를 열면 볼 수 있습니다.
Aldin Kovačević , 뼈대 및 문서에 대한 초기 작업 - Aldin-SXR
뼈대는 MIT 라이센스에 따라 라이센스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
작업이 진행 중입니다.
