Support for string:uuid about phpswaggergen HOT 9 CLOSED

I missed the part of the OpenAPI spec that says you can add custom formats. Will add it tomorrow.
It should actually make the code a bit better by allowing nicer error messages.

from phpswaggergen.

Have you tried using parameter definitions? I think you can define the type once, then use it globally.

Though it might be a good idea to include some pre-defined and well-recognized default formats such as RFC-4122 format UUID's.

from phpswaggergen.

I am working with parameter definitions and this is what I've got.

What I've got

/**
 * rest\query? string userId
 */

{
    "name": "userId",
    "in": "query",
    "type": "string"
}

What I want:

{
    "name": "userId",
    "in": "query",
    "type": "string",
+   "format": "uuid"
}

With your RFC-4122 suggestion:

{
    "name": "userId",
    "in": "query",
    "type": "string",
+   "format": "uuid",
+   "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
}

What datetime does (similar to what I want)

/**
 * rest\query? datetime createdAt
 */

{
    "name": "createdAt",
    "in": "query",
    "type": "string",
    "format": "date-time"
}

Proposal

/**
 * rest\query? uuid userId
 */

I believe that would mean updating PHPSwaggerGen/SwaggerGen/Swagger/Type/StringType.php with:

    private static $formats = array(
        'string' => '',
        'byte' => 'byte',
        'binary' => 'binary',
        'password' => 'password',
        'enum' => '',
+       'uuid' => 'uuid',
    );

I would prefer instead to specify a format along with the type, but I wouldn't know how to express it nor build it.

Crappy example below:

/**
 * rest\query? string{"type":"uuid"} userId
 */

Here's an example of how zircote/swagger-php does it:

/**
 *     @SWG\Parameter(
 *         name="userId",
 *         in="query",
 *         type="string",
 *         format="uuid",
 *         required=false,
 *     ),
 */

While I think zircote/swagger-php's composition is extremely verbose and long-winded (most of my annotations tower over my code!), it does allow me to describe formats.

from phpswaggergen.

I'm working on a mechanism for including uuid (and possibly others), but am still working on a simple syntax. However, Swaggergen currently already supports patterns and such:

/**
 * rest\query? string(^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$) userid
 */

This works just fine. The only problem is the difficult syntax.

What I'm currently trying to do is boil it down to something like

/**
 * rest\query? uuid userid
 */

The reason I'm still working on it, is because I'm conflicted about the syntax. This might conflict with people who have made their own uuid definition. I guess an RFC-4122 compliant UUID wouldn't be much of a problem, but perhaps you subject suggests a nicer solution to this problem:

/**
 * rest\query? string:uuid userid
 */

But that would require the user to know that a UUID's is a type of string internally. Ideally, the user shouldn't need any knowledge of the internals or the Swagger/Open-API specification.

I'm edging on the former (just uuid), but would like to have a mechanism in place to allow users to disable/enable and possibly extend these types, so I can introduce a lot more (i.e. email, zipcode, iso-locale, currency, etc), without conflicting with types defined by the user.
Perhaps prefering definition over local type might be a solution to this problem, effectively allowing the user to overwrite builtin types should they so desire (or more significantly; should they have already done so before a new type is introduced in Swaggergen).

from phpswaggergen.

Implemented rest\query? uuid userid type format in v2.3.8.

The builtin should also be available wherever string is recognized as a type.

The UUID regex I enforces the M and N bits and requires lowercase, as per strict interpretation of the RFC-4122 specs (so 123e4567-e89b-12d3-a456-426655440000 is valid, 123e4567-e89b-62d3-a456-426655440000 is not).

Also implemented overwriting type definitions with models for backwards compatibility in the future.

Could you please test it and (hopefully) confirm.

from phpswaggergen.

I'm glad we share the same view and internal conflict on how to design a fix. 😄

I very much like your short-hand proposal of:

/**
 * @rest\query? string:uuid userid
 */

I disagree though that it forces users to understand more about internals. If someone chooses to specify:

/**
 * @rest\query? string:foobar userid
 */

it would simply resolve to

{
    "name": "userId",
    "in": "query",
    "type": "string",
+   "format": "foobar"
}

Library support for specific internal formats is an added benefit.

As for how to implement a fix. I really don't even know how SwaggerGen would load classes apart from its own. So I don't quite understand how there could be user-defined uuid definitions out there in the wild. But if you want to be the most compatible, perhaps not including the pattern with the format would be the way to go. (I acknowledge that it is complete contradiction to adding a useful string:uuid)

from phpswaggergen.

I prefer to stick with the solution in v2.3.8:

/**
 * @rest\query? uuid userid
 */

The "user-defined" is mostly to deal with responses, where one could create an object definition named uuid using a @rest\definition uuid statement. I admit that it's unlikely that somebody would have defined their own object with a name of uuid, but it's mostly to prevent such problems in the future, if (more likely, "when") builtin types are added in the future. I can imagine adding similar builtins for ipv4, ipv6, url, email, etc.

from phpswaggergen.

For whatever reason, I missed that you actually supplied a fix. So firstly, THANK YOU!

I am testing it right now and it doesn't look like it's supplying a format.

I am using this library in combination with another closed lib to actually code-gen input validation, and "format": "uuid" is actually a contract there.

Given datetime includes format with its output, would it be possible to add format to the new uuid def, as well?

from phpswaggergen.

v2.3.9 has custom format for uuid type.
Also improved exception messages naming the correct format for string and descendants.
Please test and confirm.

from phpswaggergen.