Git Product home page Git Product logo

vanderlee / phpswaggergen Goto Github PK

View Code? Open in Web Editor NEW
41.0 5.0 16.0 1.8 MB

PHP library to generate Swagger/OpenAPI REST API documentation files from comments in PHP source code.

Home Page: http://vanderlee.github.io/PHPSwaggerGen

License: MIT License

PHP 16.46% CSS 2.97% JavaScript 80.22% HTML 0.34%
php swagger swagger2 swagger-spec openapi openapi-spec php7 php5 php53-compatible hhvm

phpswaggergen's Issues

Multiple definitions exist for class TestCase

PHPStorm gives warning "Multiple definitions exist for class TestCase" when writing unit tests for a project that has PHPSwaggerGen as a dependency. This causes autocomplete ($this->assert) to not work. I control click on TestCase and see the two definitions:

TestCase vendor/phpunit/phpunit/src/Framework
TestCase vendor/vanderlee/swaggergen/tests/bootstrap.php

It looks like bootstrap.php does some autoloading/aliasing which may be causing this. When I remove PHPSwaggerGen dependency, the warning goes away and autocomplete works.

Note that I am installing PHPUnit using this in my project composer.json

"require-dev": {
"phpunit/phpunit": "^6.2",
}

screen shot 2017-07-29 at 9 57 03 am

Preserve EOL to be able to format description

At the moment the following code will collapse everything into one line. It makes the description harder to read once rendered in Swagger UI, and prevent using Markdown syntax to format things like lists.

 * @rest\description Useful endpoint that does 2 things:
 * - this
 * - and that

Actual result:

"description":"Useful endpoint that does 2 things: - this - and that"

Expected result:

"description":"Useful endpoint that does 2 things:\n - this\n - and that"

Is there any way to preserve the end of line?

Suppress 'exclusive(Max|Min)imum' for unbounded range ends

JSON schema spec (the version used in OAS2) specifies that exclusiveMinimum/exclusiveMaximum should only be present when corresponding maximum/minimum (spec link). SwaggerGen, however, emits exclusive* fields for unbounded range ends:

api Test
endpoint /positive-integer
method GET
response 200 int[1,>

results in

"schema": {
  "type": "integer",
  "format": "int32",
  "minimum": 1,
  "exclusiveMaximum": true
}

Model inside a model support in response definition

I have the following model definitions:

/**
 * @rest\model address object defining station address.
 * @rest\property string address_line1 address line1
 * @rest\property string address_line2 address line2
 * @rest\property string city city
 * @rest\property string state state
 * @rest\property string postal_code postal code
 * @rest\property string country_code country code
 * @rest\property string phone phone
 * @rest\property string fax fax
 *
 * @rest\model stations Returns list of station for a given supplier id.
 * @rest\property int id supplier Id
 * @rest\property int supplier supplier Id
 * @rest\property string name  Supplier Name
 * @rest\property address Address Station Address
 * @rest\property string latitude latitude
 * @rest\property string longitude longitude
 * @rest\property string timezone timezone
 * @rest\property string station_type Station Type
 */

and later on declaring the response type as follows:

 /** @rest\endpoint /stations/{supplier_id}
     * @rest\method GET Returns list of station for a given supplier id.
     * @rest\response 200 stations
    */

so I'm trying to make a reference of a model inside another model. but when I execute, I get the following exception: Property format not recognized: 'address'

is model inside a model supported the same way as an array of models?

if the definition is changed as follows, the generation executes successfuly, but does not match the real output of my API

/**
 * @rest\model address object defining station address.
 * @rest\property string address_line1 address line1
 * @rest\property string address_line2 address line2
 * @rest\property string city city
 * @rest\property string state state
 * @rest\property string postal_code postal code
 * @rest\property string country_code country code
 * @rest\property string phone phone
 * @rest\property string fax fax
 *
 * @rest\model stations Returns list of station for a given supplier id.
 * @rest\property int id supplier Id
 * @rest\property int supplier supplier Id
 * @rest\property string name  Supplier Name
 * @rest\property array(address) Address Station Address
 * @rest\property string latitude latitude
 * @rest\property string longitude longitude
 * @rest\property string timezone timezone
 * @rest\property string station_type Station Type
 */

thank you

Comments ignored with docblock (/**) syntax

I'm trying to use this library but I'm having a strange behavior that I don't understand.

I'm using Slim Framework, so an API endpoint looks like:

$app->get('/v1/users/{id:[0-9]+}', function ($request, $response, $args) {
   // ...
});

When adding comments with /** */ they are ignored. The following code does not work:

/**
 * @rest\endpoint /v1/users/{id}
 * @rest\method GET Return a JSON with all the user attributes
 * @rest\path Int id The ID of the User
 * @rest\require api_key
 * @rest\response 200 User
 */
$app->get('/v1/users/{id:[0-9]+}', function ($request, $response, $args) {
   // ...
});

However when adding comments with /* */ it works. The following code works:

/*
 * @rest\endpoint /v1/users/{id}
 * @rest\method GET Return a JSON with all the user attributes
 * @rest\path Int id The ID of the User
 * @rest\require api_key
 * @rest\response 200 User
 */
$app->get('/v1/users/{id:[0-9]+}', function ($request, $response, $args) {
   // ...
});

Based on the documentation in the README, I'm expecting both versions to work the same. Any idea? Am I doing something wrong?

Support for string:uuid

Is it reasonable to suggest support for uuid strings? I understand that it is not required within spec, however the option to specify type (string) and format (uuid) would aid in describing an attribute.

Thoughts?

PHP 8 error: array and string offset access with curly braces

The library is not compatible with PHP 8.0 due two syntax errors.

Fatal error: Array and string offset access syntax with curly braces is no longer supported in SwaggerGen\Swagger\Type\AbstractType.php on line 96

Fatal error: Array and string offset access syntax with curly braces is no longer supported in SwaggerGen\Swagger\Swagger.php on line 236

additionalProperties support

I'm going to propose PR for additionalProperties object type attribute, and wanted to check with you on the inline definition format I envision:

object(type)
object(propName:type,propName2:type,type)
object(type,propName:type,...,type) // errors out with 
                                    // 'duplicate additionalProperties type specified'
{[integer]} // string -> array of int hash

The command form would be:

additionalproperties type // a bit of a mouthful, 
                          // but close to the spec language on the other hand

Default string value with spaces

For string type, it would be useful to define default values with white spaces when the default text is quoted. For example:

* @rest\property string="Ubuntu 18.04 LTS" os Operating system

Currently, the default value cannot contain whitespaces.

(Feature request)

Insert content of preprocessor variable into documentation

Besides just checking if a preprocessor variable has a given value (@rest\if name value) it would be very helpful to have its value inserted somewhere inside the documentation.
For example instead of incrementing the API version manually as in
// @rest\version 0.9.14

I would like to have it changed automatically like:
// @rest\version {myversion}
$SwaggerGen->define('myversion', 'generated-version');

Should output:
"info": { "version": "generated-version" }

Instead of using {placeholder} you could use @rest\var(placeholder) or something similar?

object(xxxx:array(),xxxxx:array()) throws exception

Hello,

The string "@rest\response 200 object(modifications:array(ModificationHistory),users:array(User))" throws an exception.

Call Stack:

SwaggerGen\Exception: Unparseable string definition: 'ModificationHistory),users:array(User' in C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\ReferenceObjectType.php:24
Stack trace:
#0 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\AbstractType.php(37): SwaggerGen\Swagger\Type\ReferenceObjectType->parseDefinition('ModificationHis...')
#1 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\ArrayType.php(188): SwaggerGen\Swagger\Type\AbstractType->__construct(Object(SwaggerGen\Swagger\Type\ArrayType), 'ModificationHis...')
#2 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\ArrayType.php(93): SwaggerGen\Swagger\Type\ArrayType->validateItems('ModificationHis...')
#3 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\ArrayType.php(69): SwaggerGen\Swagger\Type\ArrayType->parseItems('array(Modificat...', Array)
#4 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\AbstractType.php(37): SwaggerGen\Swagger\Type\ArrayType->parseDefinition('array(Modificat...')
#5 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\Property.php(77): SwaggerGen\Swagger\Type\AbstractType->__construct(Object(SwaggerGen\Swagger\Type\Property), 'array(Modificat...')
#6 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\ObjectType.php(61): SwaggerGen\Swagger\Type\Property->__construct(Object(SwaggerGen\Swagger\Type\ObjectType), 'array(Modificat...')
#7 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\ObjectType.php(42): SwaggerGen\Swagger\Type\ObjectType->parseProperties('object(modifica...', Array)
#8 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Type\AbstractType.php(37): SwaggerGen\Swagger\Type\ObjectType->parseDefinition('object(modifica...')
#9 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Schema.php(76): SwaggerGen\Swagger\Type\AbstractType->__construct(Object(SwaggerGen\Swagger\Schema), 'object(modifica...')
#10 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Response.php(113): SwaggerGen\Swagger\Schema->__construct(Object(SwaggerGen\Swagger\Response), 'object(modifica...')
#11 C:\Application\vendor\vanderlee\swaggergen\SwaggerGen\Swagger\Operation.php(142): SwaggerGen\Swagger\Response->__construct(Object(SwaggerGen\Swagger\Operation), 200, 'object(modifica...', '')

Property definitions should accept further (type-specific) commands

Documentation is not clear about this quirk, but I think it should be possible to compile this definition:

definition ClassName
title ClassName
property string type
enum ClassName
property int meaningOfLifeTheUniverseAndEverything
enum 42

where enum ClassName defines the only possible value for type property, and enum 42 is the only allowed value for meaningOfLifeTheUniverseAndEverything.

Meanwhile Schema forwards handleCommand to ObjectType and that does not accept subcommands for current property being processed. While it's possible to define fixed value for string properties using property enum(ClassName) type, I don't see any way to define fixed value for integer properties (and other types).

PHP Parser fails when parsing @rest\property!

The regex on this line:

if (preg_match('~^@' . preg_quote(self::COMMENT_TAG) . '\\\\([a-z][-a-z]*\\??)\\s*(.*)$~', $line, $match) === 1) {

Should be changed to: '~^@' . preg_quote(self::COMMENT_TAG) . '\\\\([a-z][-a-z]*[?!]?)\\s*(.*)$~'

It fails when attempting to parse the following:

/**
 * @rest\definition Account
 * @rest\property! int[0,] id
 */

The resulting matches array looks like this:

Array
(
    [0] => @rest\property! int[0,] id
    [1] => property
    [2] => ! int[0,] id
)

It is expected to look like this:

Array
(
    [0] => @rest\property! int[0,] id
    [1] => property!
    [2] => int[0,] id
)

I am not particularly good with PHPUnit, so feel free to create a test for this case.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.