vanderlee / phpswaggergen Goto Github PK

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?

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
}

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

Hi, the example of Swagger documentation found on the creating documentation page doesn't parse.

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...', '')

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

Swagger spec says HEAD method is allowed: https://swagger.io/specification/#fixed-fields-33
However swaggergen does not list it as acceptable:

The regex on this line:

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.

Dear Developer(s),

I want to ask you to develop PHPSwaggerGen to support example attribute for swagger.
What I mean?

responses:
200:
description: 'Succes data request'
schema:
properties:
code:
type: string
example: "SUCCESS"
message:
type: string
example: "Your request was successfully!"

More about this attribute: https://swagger.io/docs/specification/adding-examples/

Would be nice to have this feature too. Thank you!

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?

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

@rest\require auth_token
@rest\require auth_code
@rest\require auth_implicit

it should be:
https://monosnap.com/file/FH4NnOGbsA97CvPPySxWrq8poefiWc.png
http://swagger.io/specification/#securityRequirementObject

but now it is elemet of array:
https://monosnap.com/file/KkSDqHfxflSB9fikwcNn11Ke51oG3e.png

Having a property or parameter with the same name in the same context twice (or more) results in duplicate outputs.

As per the documentation (http://php.net/manual/en/function.json-encode.php), all associative arrays are turned into JSON objects. In some cases this violates the Swagger spec, such as with security options on routes, where it expects an array. This behaviour also seems to happen in the YAML output, so perhaps this is consistent in PHP's built in functions.

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)

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?

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).

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",
}

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?