export-api-def: Refinement for operationId?

[hideya]

While trying out slc loopback:export-api-def and swagger codegen to generate client side SDKs, I noticed that swagger codegen uses operationId as the name for the generated method on the client side.

Currently, operationId sometimes becomes like User.prototype.__findById__accessTokens. Then, the swagger.io generated Objective-C method for this becomes userPrototypeFindByIdAccessTokens.... It looks unnecessarily wordy. For Swift, the method name becomes user.prototype.FindByIdAccessTokens (this fails to compile as the Swing codegen doesn't escape "."s included in the method name. It can/should be fixed in the Swift codegen, but the issue of wordy method name still remains).

As it seems like a convention that usage of operationId for method name for generated code, I think it would better make operationId simpler and well suited for method name.

[bajtos]

@hideya could you please send swift method names generated for these server methods:

• User.findById
• User.prototype.updateAttributes

Is the "user" part encoded inside the swift method name, or is it dropped as it's a class name?

[bajtos]

Perhaps also few snippets of Swagger code showing how these methods are invoked?

[hideya]

Usage of swagger codegen output:

    // modify -[XXConfiguration init] to add `self.host = @"http://localhost:3000/api";`
    XXCoffeeShopApi *coffeeShopApi = [[XXCoffeeShopApi alloc] init];

    __block XXCoffeeShop *coffeeShop = [[XXCoffeeShop alloc] init];
    coffeeShop.name = @"Shop Name";
    coffeeShop.city = @"City Name";

    [coffeeShopApi coffeeShopCreateWithCompletionBlock: coffeeShop
                                     completionHandler: ^(XXCoffeeShop* output, NSError* error)
    {
        NSLog(@"create: %@", output);
        coffeeShop = output;

        [coffeeShopApi coffeeShopFindByIdWithCompletionBlock: [coffeeShop._id stringValue]
                                                      filter: nil
                                           completionHandler: ^(XXCoffeeShop* output, NSError* error)
         {
            NSLog(@"find: %@", output);

            coffeeShop.name = @"New Name";
            [coffeeShopApi coffeeShopUpsertWithCompletionBlock: coffeeShop
                                             completionHandler: ^(XXCoffeeShop* output, NSError* error)
             {
                 NSLog(@"upsert: %@", output);

                 [coffeeShopApi coffeeShopDeleteByIdWithCompletionBlock: [coffeeShop._id stringValue]
                                                      completionHandler: ^(XXInlineResponse200* output, NSError* error)
                  {
                      NSLog(@"delete: %@", output);
                  }];
             }];
        }];
    }];

Usage of our LB SDK codegen output:

    LBRESTAdapter *adapter = [LBRESTAdapter adapterWithURL:[NSURL URLWithString:@"http://localhost:3000/api"]];
    CoffeeShopRepository *coffeeShopRepo = (CoffeeShopRepository *)[adapter repositoryWithClass:[CoffeeShopRepository class]];

    CoffeeShop *coffeeShop = (CoffeeShop *)[coffeeShopRepo modelWithDictionary:nil];
    coffeeShop.name = @"Shop Name";
    coffeeShop.city = @"City Name";

    [coffeeShop saveWithSuccess:^{
        NSLog(@"created");

        [coffeeShopRepo findById:coffeeShop._id
                         success:^(LBPersistedModel *model)
        {
            NSLog(@"find: %@", model);

            coffeeShop.name = @"new name";
            [coffeeShop saveWithSuccess:^{

                NSLog(@"upsert: %@", coffeeShop);

                [coffeeShop destroyWithSuccess:^{

                    NSLog(@"deleted");

                } failure:^(NSError *error) { }];
            } failure:^(NSError *error) { }];
        } failure:^(NSError *error) { }];
    } failure:^(NSError *error) { }];

[bajtos]

@hideya please talk to maintainers of Swift Code-Gen and get their thoughts on what would be the best way to improve this. Should we go with a more OOP styled code? Should we change LB swagger gen to produce different (shorter?) method names?

[hideya]

@bajtos as a starter, I filed an Issue against Swift codegen as failed escape of special characters seems a bug to me: swagger-api/swagger-codegen#2095

I thought about OOP styled code generation, and realised it would be quite a big discussion -- currently, server API consists just a set of methods, but we need to add meta info or conventions to digest them in OO style -- e.g. how to distinguish between class vs instance methods? how to identify the target instance? possibly a use of ID argument? then what type? how to tell which argument is ID? etc.

[hideya]

@bajtos FYI, I contributed PR swagger-api/swagger-codegen#2112 that fixes Issue swagger-api/swagger-codegen#2095 I filed, and the PR has been merged :-)

[hideya]

@bajtos I realised that OpenAPI Specification says that operationId is:

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.

Currently operationId can be something like the following:

operationId: 'CoffeeShop.exists__get_CoffeeShops_{id}_exists'

This turns into a method name like (in Swift):

public class func coffeeShopExistsGetCoffeeShopsidExists(id id: String) -> RequestBuilder<Inline_response_200> {

which is not human friendly. Because of the above mentioned description, I think export-api-def needs to generate operationId with attention to human friendliness in mind.

[bajtos]

I think we will need to implement this soon for the integration @chayab is working on.