laminas-api-tools / api-tools-documentation-swagger Goto Github PK

Originally posted by @sk335577 at zfcampus/zf-apigility-documentation-swagger#36

Feature Request

Summary

To be prepared for the december release of PHP 8.0, this repository has some additional TODOs to be tested against the new major version.

In order to make this repository compatible, one has to follow these steps:

• Modify composer.json to provide support for PHP 8.0 by adding the constraint ~8.0.0
• Modify composer.json to drop support for PHP less than 7.3
• Modify composer.json to implement phpunit 9.3 which supports PHP 7.3+
• Modify .travis.yml to ignore platform requirements when installing composer dependencies (simply add --ignore-platform-reqs to COMPOSER_ARGS env variable)
• Modify .travis.yml to add PHP 8.0 to the matrix (NOTE: Do not allow failures as PHP 8.0 has a feature freeze since 2020-08-04!)
• Modify source code in case there are incompatibilities with PHP 8.0

I added this field to be able to personalized methods of the sdks generated with swagger-codegen and zf-apigility-documentation-swagger.

Note: this depends on zfcampus/zf-apigility-documentation#70

Originally posted by @garygitton at zfcampus/zf-apigility-documentation-swagger#38

Let's say my apigility runs under http://example.com/api, with a service /test thus available under http://example.com/api/test. My issue: The buttons to "Try it out!" are sending their requests to http://example.com/test, which ofc will result in a 500 error every time.

I found that I could fix this in this module's Service.php by modifying $this->baseUrl (appending '/api'), but obviously that's not the intended way to do it.

So is this something I am doing wrong (and if so, how do I do it right?) or something the module is doing wrong?

Originally posted by @marartner at zfcampus/zf-apigility-documentation-swagger#32

The throbber.gif file uri is set directly in JavaScript, with a relative path ; as a consequence, the file is not loaded correctly (and the alternative text is displayed)

I don't know how to fix it properly

Thanks

Originally posted by @Gounlaf at zfcampus/zf-apigility-documentation-swagger#10

I updated Swagger UI to 3.13.1 as well as OpenApi documentation format. How better to merge it here? As it's complex update I am not sure how better to do it.

Originally posted by @tasselchof at zfcampus/zf-apigility-documentation-swagger#35

The Swagger output only contains the default input filter from the config, but not the method specific ones. My api in this example is called OrdersApi, and below are excerpts from /apigility/documentation/OrdersApi-v1 that whows the difference:

Accept: application/json

{
    "name": "OrdersApi",
    "version": "1",
    "services": [
        {
            "name": "OrderListener",
            "route": "/api/order/listener[/:id]",
            "fields": {
                "input_filter": {
                    "worker": {
                        "description": "The worker name",
                        "required": true,
                        "type": "",
                        "example": null
                    },
                    "revision": {
                        "description": "Current revision number",
                        "required": true,
                        "type": "",
                        "example": null
                    }
                },
                "POST": {
                    "worker": {
                        "description": "The worker name",
                        "required": true,
                        "type": "",
                        "example": null
                    }
                }
            }
        }
    ]
}

Accept: application/vnd.swagger+json

{
    "swagger": "2.0",
    "info": {
        "title": "OrdersApi",
        "version": "1"
    },
    "tags": [
        {
            "name": "OrderListener"
        }
    ],
    "paths": {
        "/api/order/listener": {
            "post": {
                "tags": [
                    "OrderListener"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/OrderListener"
                        }
                    }
                ]
            }
        },
        "/api/order/listener/{id}": {
            "put": {
                "tags": [
                    "OrderListener"
                ],
                "parameters": [
                    {
                        "in": "path",
                        "name": "id",
                        "description": "URL parameter id",
                        "type": "string",
                        "required": true,
                        "minimum": 0,
                        "maximum": 1
                    },
                    {
                        "in": "body",
                        "name": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/OrderListener"
                        }
                    }
                ]
            }
        }
    },
    "definitions": {
        "OrderListener": {
            "type": "object",
            "properties": {
                "worker": {
                    "type": "string",
                    "description": "The worker name"
                },
                "revision": {
                    "type": "string",
                    "description": "Current revision number"
                }
            },
            "required": [
                "worker",
                "revision"
            ]
        }
    }
}

Config

'zf-content-validation' => [
    'OrdersApi\\V1\\Rest\\Order\\Listener\\Controller' => [
        'input_filter' => 'OrdersApi\\V1\\Rest\\Order\\Listener\\Validator',
        'POST' => 'OrdersApi\\V1\\Rest\\Order\\Listener\\ValidatorCreate',
    ],
],
'input_filter_specs' => [
    'OrdersApi\\V1\\Rest\\Order\\Listener\\Validator' => [
        [
            'required' => true,
            'validators' => [
                [
                    'name' => \Zend\Validator\NotEmpty::class,
                    'options' => [],
                ],
                [
                    'name' => \Zend\Validator\StringLength::class,
                    'options' => [],
                ],
            ],
            'filters' => [],
            'name' => 'worker',
            'description' => 'The worker name',
        ],
        [
            'required' => true,
            'validators' => [
                [
                    'name' => \Zend\Validator\NotEmpty::class,
                    'options' => [],
                ],
                [
                    'name' => \Zend\Validator\Digits::class,
                    'options' => [],
                ],
            ],
            'filters' => [],
            'name' => 'revision',
            'description' => 'Current revision number',
        ],
    ],
    'OrdersApi\\V1\\Rest\\Order\\Listener\\ValidatorCreate' => [
        [
            'required' => true,
            'validators' => [
                [
                    'name' => \Zend\Validator\NotEmpty::class,
                    'options' => [],
                ],
                [
                    'name' => \Zend\Validator\StringLength::class,
                    'options' => [],
                ],
            ],
            'filters' => [],
            'name' => 'worker',
            'description' => 'The worker name',
        ],
    ],
],

Originally posted by @Jakovitz at zfcampus/zf-apigility-documentation-swagger#40

Currently, only optional params are exposed when looking at a service.

Example:

It'd be awesome to add support for non-optional params

Example:

In Service.php, in the toArray() method, this is happening:

$routeWithReplacements = str_replace(['[', ']', '{/', '{:'], ['{', '}', '/{', '{'], $service->route);

Changing it to:

$routeWithReplacements = preg_replace('#\[?\/:(\w+)\]?#', '/{$1}', $service->route);

will give the results I'd like to see.

If this change is acceptable, I can go ahead and make a PR, otherwise, I'm open to hearing other ideas to add support for this.

Originally posted by @stringerbell at zfcampus/zf-apigility-documentation-swagger#17

Provide a narrative description of what you are trying to accomplish:

• [x ] Are you fixing a bug?

  • Detail how the bug is invoked currently.
    \ZF\Apigility\Documentation\Swagger\Service::getRouteWithReplacements was not handling well all the route

  • Detail the original, incorrect behavior.
    The method was not handling route like /user/:user_id

  • Detail the new, expected behavior.
    It now handle it

Originally posted by @garygitton at zfcampus/zf-apigility-documentation-swagger#39

Should it be updated (where to?) or removed?

Originally posted by @carnage at zfcampus/zf-apigility-documentation-swagger#31

Bug Report

Summary

The authorization input is not displayed in each resource of my API neither in the top bar

Current behavior

Authorization input is not displayed

How to reproduce

Generate a swagger json with:

laminas-api-tools/api-tools-documentation: 1.3.0
laminas-api-tools/api-tools: 1.4.1

Expected behavior

Display the authorization input.

Hi!

Why there there are two parameters:

'minimum'     => 0,
'maximum'     => 1,

I have URL path like that:

{
            "in": "path",
            "name": "service_point_id",
            "description": "URL parameter service_point_id",
            "type": "string",
            "required": true
}

If I pass service_point_id = 230419 Swagger UI does not allow it as it is not passing this minimum and maximum values.

Bug Report

Release of Version 1.4.0 claims to have PHP 8.0 compatibility.
Missing Version in composer.json

Summary

The release is missing the correct required PHP specifiactins in composer.json

Current behavior

The version 1.4.0 will not be installed with composer if you are running PHP 8.0

How to reproduce

Have PHP 8.0 running - try to install / upgrade package via composer.
Setup will break with:
laminas-api-tools/api-tools-documentation-swagger 1.4.0 requires php ^7.3 -> your php version (8.0.3) does not satisfy that requirement.

Expected behavior

Package installs with running PHP 8

Feature Request

Summary

Add support for PHP 8.2

hi there,

i'd like to see my whitelisted collection params from zf-rest.MyController.collection_query_whitelist show up in the Swagger UI as form inputs. in order to do that, i think collection_query_whitelist would need to be added to the \ZF\Apigility\Documentation\Service generated by \ZF\Apigility\Documentation\ApiFactory::createService in zfcampus/zf-apigility-documentation, and \ZF\Apigility\Documentation\Swagger\Service::toArray would need to updated in this package to transform collection_query_whitelist into Swagger parameters.

does this functionality already exist and i've misconfigured something? if not, and if this sounds like a useful addition then i'll get to work.

thanks!

Originally posted by @abacaphiliac at zfcampus/zf-apigility-documentation-swagger#30

I was not able to find an open or closed issue matching what I'm seeing.

Would be great if on the swagger documentation page the authorization & authentication details would show up for each method and resource.

Originally posted by @Don-Ron at zfcampus/zf-apigility-documentation-swagger#41

Feature Request

Summary

As decided during the Technical-Steering-Committee Meeting on August 3rd, 2020, Laminas wants to implement vimeo/psalm in all packages.

Implementing psalm is quite easy.

Required

• Create a psalm.xml in the project root
• Copy and paste the contents from this psalm.xml.dist
• Run $ composer require --dev vimeo/psalm
• Run $ vendor/bin/psalm --set-baseline=psalm-baseline.xml
• Add a composer script static-analysis with the command psalm --shepherd --stats
• Add a new line to script: in .travis.yml: - if [[ $TEST_COVERAGE == 'true' ]]; then composer static-analysis ; fi
• Remove phpstan from the project (phpstan.neon.dist, .travis.yml entry, composer.json require-dev and scripts)

Optional

• Fix as many psalm errors as possible.

Switch from Travis-CI to GHA CI workflow, as documented at https://gist.github.com/weierophinney/b003e50c3c2667d08076caf31ebd36a4

Is there a way to disable documentation for a service. so it shouldn't get listed in the API.
The reason is that sometimes we want to have some of the services that are meant to be internal and therefore the documentation shouldn't be public

Originally posted by @mmjamal at zfcampus/zf-apigility-documentation-swagger#15