From 99646e6436e988faa39ff7b9b70ea9b1d7856971 Mon Sep 17 00:00:00 2001 From: Yuriy Belenko Date: Tue, 21 Aug 2018 15:25:43 +0500 Subject: [PATCH] [Slim] Update main documentation (#839) * [Slim] Update main documentation Kotlin server README has been used as a ref. There are no links to apis and models docs, because Slim codegen doesn't provide them right now. Also I'm not sure about white spaces, but we can change it anytime in future. * [Slim] Refresh samples --- .../resources/php-slim-server/README.mustache | 73 ++++++++-- .../petstore-security-test/php-slim/README.md | 60 +++++++- samples/server/petstore/php-slim/README.md | 132 ++++++++++++++++-- 3 files changed, 240 insertions(+), 25 deletions(-) diff --git a/modules/openapi-generator/src/main/resources/php-slim-server/README.mustache b/modules/openapi-generator/src/main/resources/php-slim-server/README.mustache index e7b73f219bf..c8375231584 100644 --- a/modules/openapi-generator/src/main/resources/php-slim-server/README.mustache +++ b/modules/openapi-generator/src/main/resources/php-slim-server/README.mustache @@ -1,22 +1,77 @@ -# OpenAPI generated server +# {{packageName}} - PHP Slim Server library for {{appName}} -## Overview -This server was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. By using the -[OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate a server stub. This -is an example of building a PHP Slim server. +[Slim Framework Documentation](https://www.slimframework.com/docs/) -This example uses the [Slim Framework](http://www.slimframework.com/). To see how to make this your own, please take a look at the template here: +## Requirements -[TEMPLATES](https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/php-slim-server/) +* Web server with URL rewriting +* PHP 5.5 or newer + +This package contains `.htaccess` for Apache configuration. +If you use another server(Nginx, HHVM, IIS, lighttpd) check out [Web Servers](https://www.slimframework.com/docs/v3/start/web-servers.html) doc. + +## Installation via [Composer](https://getcomposer.org/) + +Navigate into your project's root directory and execute the bash command shown below. +This command downloads the Slim Framework and its third-party dependencies into your project's `vendor/` directory. +```bash +$ composer install +``` + +## Start devserver + +Run the following command in terminal to start localhost web server, assuming `./php-slim-server/` is public-accessible directory with `index.php` file: +```bash +$ php -S localhost:8888 -t php-slim-server +``` +> **Warning** This web server was designed to aid application development. +> It may also be useful for testing purposes or for application demonstrations that are run in controlled environments. +> It is not intended to be a full-featured web server. It should not be used on a public network. + +## Run tests + +This package uses PHPUnit 4.8 for unit testing. +[Test folder]({{testBasePath}}) contains templates which you can fill with real test assertions. +How to write tests read at [PHPUnit Manual - Chapter 2. Writing Tests for PHPUnit](https://phpunit.de/manual/4.8/en/writing-tests-for-phpunit.html). + +Command | Tool | Target +---- | ---- | ---- +`$ composer test` | PHPUnit | All tests +`$ composer run test-apis` | PHPUnit | Apis tests +`$ composer run test-models` | PHPUnit | Models tests + +{{#generateApiDocs}} +## API Endpoints + +All URIs are relative to *{{{basePath}}}* + +Class | Method | HTTP request | Description +------------ | ------------- | ------------- | ------------- +{{#apiInfo}}{{#apis}}{{#operations}}{{#operation}}*{{classname}}* | **{{operationId}}** | **{{httpMethod}}** {{path}} | {{#summary}}{{{summary}}}{{/summary}} +{{/operation}}{{/operations}}{{/apis}}{{/apiInfo}} +{{/generateApiDocs}} + +{{#generateModelDocs}} +## Models + +{{#modelPackage}} +{{#models}}{{#model}}* {{{modelPackage}}}\{{{classname}}} +{{/model}}{{/models}} +{{/modelPackage}} +{{^modelPackage}} +No model defined in this package +{{/modelPackage}} +{{/generateModelDocs}} {{#authMethods}} {{^hasMore}} ## Authentication + {{/hasMore}} {{/authMethods}} {{#authMethods}} {{#isBasic}} -> Important! To make Basic Authentication work you need to implement `authenticator` function in [SlimRouter]({{srcBasePath}}/SlimRouter.php) class. -> Documentation [tuupola/slim-basic-auth](https://github.com/tuupola/slim-basic-auth) +> Important! To make Basic Authentication work you need to implement `authenticator` function in [SlimRouter]({{srcBasePath}}/SlimRouter.php) class. +> Documentation [tuupola/slim-basic-auth](https://github.com/tuupola/slim-basic-auth#readme) {{/isBasic}} {{/authMethods}} diff --git a/samples/server/petstore-security-test/php-slim/README.md b/samples/server/petstore-security-test/php-slim/README.md index 8a2df551ce7..337746cd020 100644 --- a/samples/server/petstore-security-test/php-slim/README.md +++ b/samples/server/petstore-security-test/php-slim/README.md @@ -1,12 +1,58 @@ -# OpenAPI generated server +# php-base - PHP Slim Server library for OpenAPI Petstore *_/ ' \" =end -- \\r\\n \\n \\r -## Overview -This server was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. By using the -[OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate a server stub. This -is an example of building a PHP Slim server. +[Slim Framework Documentation](https://www.slimframework.com/docs/) -This example uses the [Slim Framework](http://www.slimframework.com/). To see how to make this your own, please take a look at the template here: +## Requirements + +* Web server with URL rewriting +* PHP 5.5 or newer + +This package contains `.htaccess` for Apache configuration. +If you use another server(Nginx, HHVM, IIS, lighttpd) check out [Web Servers](https://www.slimframework.com/docs/v3/start/web-servers.html) doc. + +## Installation via [Composer](https://getcomposer.org/) + +Navigate into your project's root directory and execute the bash command shown below. +This command downloads the Slim Framework and its third-party dependencies into your project's `vendor/` directory. +```bash +$ composer install +``` + +## Start devserver + +Run the following command in terminal to start localhost web server, assuming `./php-slim-server/` is public-accessible directory with `index.php` file: +```bash +$ php -S localhost:8888 -t php-slim-server +``` +> **Warning** This web server was designed to aid application development. +> It may also be useful for testing purposes or for application demonstrations that are run in controlled environments. +> It is not intended to be a full-featured web server. It should not be used on a public network. + +## Run tests + +This package uses PHPUnit 4.8 for unit testing. +[Test folder](test) contains templates which you can fill with real test assertions. +How to write tests read at [PHPUnit Manual - Chapter 2. Writing Tests for PHPUnit](https://phpunit.de/manual/4.8/en/writing-tests-for-phpunit.html). + +Command | Tool | Target +---- | ---- | ---- +`$ composer test` | PHPUnit | All tests +`$ composer run test-apis` | PHPUnit | Apis tests +`$ composer run test-models` | PHPUnit | Models tests + +## API Endpoints + +All URIs are relative to *http://petstore.swagger.io *_/ ' \" =end -- \\r\\n \\n \\r/v2 *_/ ' \" =end -- \\r\\n \\n \\r* + +Class | Method | HTTP request | Description +------------ | ------------- | ------------- | ------------- +*FakeApi* | **testCodeInjectEndRnNR** | **PUT** /fake | To test code injection *_/ ' \" =end -- \\r\\n \\n \\r + + +## Models + +* OpenAPIServer\Model\ModelReturn -[TEMPLATES](https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/php-slim-server/) ## Authentication + diff --git a/samples/server/petstore/php-slim/README.md b/samples/server/petstore/php-slim/README.md index 9847411dd75..85f8dfa9803 100644 --- a/samples/server/petstore/php-slim/README.md +++ b/samples/server/petstore/php-slim/README.md @@ -1,14 +1,128 @@ -# OpenAPI generated server +# php-base - PHP Slim Server library for OpenAPI Petstore -## Overview -This server was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. By using the -[OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate a server stub. This -is an example of building a PHP Slim server. +[Slim Framework Documentation](https://www.slimframework.com/docs/) -This example uses the [Slim Framework](http://www.slimframework.com/). To see how to make this your own, please take a look at the template here: +## Requirements + +* Web server with URL rewriting +* PHP 5.5 or newer + +This package contains `.htaccess` for Apache configuration. +If you use another server(Nginx, HHVM, IIS, lighttpd) check out [Web Servers](https://www.slimframework.com/docs/v3/start/web-servers.html) doc. + +## Installation via [Composer](https://getcomposer.org/) + +Navigate into your project's root directory and execute the bash command shown below. +This command downloads the Slim Framework and its third-party dependencies into your project's `vendor/` directory. +```bash +$ composer install +``` + +## Start devserver + +Run the following command in terminal to start localhost web server, assuming `./php-slim-server/` is public-accessible directory with `index.php` file: +```bash +$ php -S localhost:8888 -t php-slim-server +``` +> **Warning** This web server was designed to aid application development. +> It may also be useful for testing purposes or for application demonstrations that are run in controlled environments. +> It is not intended to be a full-featured web server. It should not be used on a public network. + +## Run tests + +This package uses PHPUnit 4.8 for unit testing. +[Test folder](test) contains templates which you can fill with real test assertions. +How to write tests read at [PHPUnit Manual - Chapter 2. Writing Tests for PHPUnit](https://phpunit.de/manual/4.8/en/writing-tests-for-phpunit.html). + +Command | Tool | Target +---- | ---- | ---- +`$ composer test` | PHPUnit | All tests +`$ composer run test-apis` | PHPUnit | Apis tests +`$ composer run test-models` | PHPUnit | Models tests + +## API Endpoints + +All URIs are relative to *http://petstore.swagger.io:80/v2* + +Class | Method | HTTP request | Description +------------ | ------------- | ------------- | ------------- +*AnotherFakeApi* | **call123TestSpecialTags** | **PATCH** /another-fake/dummy | To test special tags +*FakeApi* | **fakeOuterBooleanSerialize** | **POST** /fake/outer/boolean | +*FakeApi* | **fakeOuterCompositeSerialize** | **POST** /fake/outer/composite | +*FakeApi* | **fakeOuterNumberSerialize** | **POST** /fake/outer/number | +*FakeApi* | **fakeOuterStringSerialize** | **POST** /fake/outer/string | +*FakeApi* | **testBodyWithFileSchema** | **PUT** /fake/body-with-file-schema | +*FakeApi* | **testBodyWithQueryParams** | **PUT** /fake/body-with-query-params | +*FakeApi* | **testClientModel** | **PATCH** /fake | To test \"client\" model +*FakeApi* | **testEndpointParameters** | **POST** /fake | Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 +*FakeApi* | **testEnumParameters** | **GET** /fake | To test enum parameters +*FakeApi* | **testInlineAdditionalProperties** | **POST** /fake/inline-additionalProperties | test inline additionalProperties +*FakeApi* | **testJsonFormData** | **GET** /fake/jsonFormData | test json serialization of form data +*FakeClassnameTags123Api* | **testClassname** | **PATCH** /fake_classname_test | To test class name in snake case +*PetApi* | **addPet** | **POST** /pet | Add a new pet to the store +*PetApi* | **findPetsByStatus** | **GET** /pet/findByStatus | Finds Pets by status +*PetApi* | **findPetsByTags** | **GET** /pet/findByTags | Finds Pets by tags +*PetApi* | **updatePet** | **PUT** /pet | Update an existing pet +*PetApi* | **deletePet** | **DELETE** /pet/{petId} | Deletes a pet +*PetApi* | **getPetById** | **GET** /pet/{petId} | Find pet by ID +*PetApi* | **updatePetWithForm** | **POST** /pet/{petId} | Updates a pet in the store with form data +*PetApi* | **uploadFile** | **POST** /pet/{petId}/uploadImage | uploads an image +*PetApi* | **uploadFileWithRequiredFile** | **POST** /fake/{petId}/uploadImageWithRequiredFile | uploads an image (required) +*StoreApi* | **getInventory** | **GET** /store/inventory | Returns pet inventories by status +*StoreApi* | **placeOrder** | **POST** /store/order | Place an order for a pet +*StoreApi* | **deleteOrder** | **DELETE** /store/order/{order_id} | Delete purchase order by ID +*StoreApi* | **getOrderById** | **GET** /store/order/{order_id} | Find purchase order by ID +*UserApi* | **createUser** | **POST** /user | Create user +*UserApi* | **createUsersWithArrayInput** | **POST** /user/createWithArray | Creates list of users with given input array +*UserApi* | **createUsersWithListInput** | **POST** /user/createWithList | Creates list of users with given input array +*UserApi* | **loginUser** | **GET** /user/login | Logs user into the system +*UserApi* | **logoutUser** | **GET** /user/logout | Logs out current logged in user session +*UserApi* | **deleteUser** | **DELETE** /user/{username} | Delete user +*UserApi* | **getUserByName** | **GET** /user/{username} | Get user by user name +*UserApi* | **updateUser** | **PUT** /user/{username} | Updated user + + +## Models + +* OpenAPIServer\Model\AdditionalPropertiesClass +* OpenAPIServer\Model\Animal +* OpenAPIServer\Model\AnimalFarm +* OpenAPIServer\Model\ApiResponse +* OpenAPIServer\Model\ArrayOfArrayOfNumberOnly +* OpenAPIServer\Model\ArrayOfNumberOnly +* OpenAPIServer\Model\ArrayTest +* OpenAPIServer\Model\Capitalization +* OpenAPIServer\Model\Cat +* OpenAPIServer\Model\Category +* OpenAPIServer\Model\ClassModel +* OpenAPIServer\Model\Client +* OpenAPIServer\Model\Dog +* OpenAPIServer\Model\EnumArrays +* OpenAPIServer\Model\EnumClass +* OpenAPIServer\Model\EnumTest +* OpenAPIServer\Model\File +* OpenAPIServer\Model\FileSchemaTestClass +* OpenAPIServer\Model\FormatTest +* OpenAPIServer\Model\HasOnlyReadOnly +* OpenAPIServer\Model\MapTest +* OpenAPIServer\Model\MixedPropertiesAndAdditionalPropertiesClass +* OpenAPIServer\Model\Model200Response +* OpenAPIServer\Model\ModelList +* OpenAPIServer\Model\ModelReturn +* OpenAPIServer\Model\Name +* OpenAPIServer\Model\NumberOnly +* OpenAPIServer\Model\Order +* OpenAPIServer\Model\OuterComposite +* OpenAPIServer\Model\OuterEnum +* OpenAPIServer\Model\Pet +* OpenAPIServer\Model\ReadOnlyFirst +* OpenAPIServer\Model\SpecialModelName +* OpenAPIServer\Model\StringBooleanMap +* OpenAPIServer\Model\Tag +* OpenAPIServer\Model\User -[TEMPLATES](https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/php-slim-server/) ## Authentication -> Important! To make Basic Authentication work you need to implement `authenticator` function in [SlimRouter](lib/SlimRouter.php) class. -> Documentation [tuupola/slim-basic-auth](https://github.com/tuupola/slim-basic-auth) + +> Important! To make Basic Authentication work you need to implement `authenticator` function in [SlimRouter](lib/SlimRouter.php) class. +> Documentation [tuupola/slim-basic-auth](https://github.com/tuupola/slim-basic-auth#readme)