[Lua] Add new Lua client generator #6252

wing328 · 2017-08-06T17:27:36Z

PR checklist

Read the contribution guidelines.
Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh and ./bin/security/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\.
Filed the PR against the correct branch: master for non-breaking changes and 3.0.0 branch for breaking (non-backward compatible) changes.

Description of the PR

Still WIP (based on #6244)

wing328 · 2017-08-06T17:44:42Z

modules/swagger-codegen/src/main/resources/lua/configuration.mustache

+	Prefix	string
+}
+
+type Configuration struct {


@daurnimator here is the configuration class for Go API client. We may need something similar in Lua API client to store the authentication setting, default header, host, basePath, etc

Don't we sort of have that already with the api class?

Yes, and I'm not saying it's a must. My suggestion is to make it more consistent with other language generator. We can put it as a day 2 requirement for reconsideration.

wing328 · 2017-08-06T17:45:52Z

modules/swagger-codegen/src/main/resources/lua/model.mustache

+  return setmetatable(t, {{classname}}_mt)
+end
+
+local function new_{{classname}}({{#vars}}{{name}}{{#hasMore}}, {{/hasMore}}{{/vars}})


@daurnimator in the constructor method signature, I've included all parameters (required, optional)

wing328 · 2017-08-06T17:47:40Z

modules/swagger-codegen/src/main/resources/lua/model.mustache

+local function new_{{classname}}({{#vars}}{{name}}{{#hasMore}}, {{/hasMore}}{{/vars}})
+  return cast_pet({
+    {{#vars}}
+    {{name}} = {{name}};


@daurnimator later we'll need to handle the situation when the JSON key name contains special character (e.g. date-time) (day 2 requirement)

For non-valid lua identifiers, the key syntax is ["f@0"]

wing328 · 2017-08-06T17:49:38Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+            return nil, err3
+        end
+        return {{{packagName}}}_{{classname}}.cast(result)
+    else


@daurnimator for 4xx and 5xx status code, we usually throw an exception in other generators and the exception object contains 3 fields: http status code, header and body (error message). Not sure if we can do something similar in Lua.

You can throw an error, but it's considered better practice to return nil, error, errno. Where error is usually a string, but could be some type of other object.

Sure, let's follow the best practice to return nil, error, errno.

wing328 · 2017-08-06T17:51:36Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+        if result == nil then
+            return nil, err3
+        end
+        return {{{packagName}}}_{{classname}}.cast(result)


@daurnimator I notice that Lua can return a list of objects so I would suggest we return the following

result (e.g. Pet, string, array of Users)

http status code

http headers

as it's just a matter of time the developers need the status code and header.

lua-http follows the http2 convention where the status code is just another header (called :status): so no need for the extra status return value.

OK. so just return result and headers then.

wing328 · 2017-08-06T17:52:42Z

@daurnimator please review my comments and the TODO in the code when you've time. Thanks!

daurnimator · 2017-08-07T01:12:33Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+  // TODO: default basePath to {{{basePath}}}
+  return setmetatable({
+    host = host;
+    basePath = basePath;


Could use basePath = basePath or {{{basePath}}} to close above TODO?

daurnimator · 2017-08-07T01:12:45Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+    basePath = basePath;
+    schemes = schemes_map;
+    default_scheme = default_scheme;
+  }, {{{pacakgeName}}}_mt)


typo? pacakgeName

daurnimator · 2017-08-07T01:14:57Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+        if result == nil then
+            return nil, err3
+        end
+        return {{{packagName}}}_{{classname}}.cast(result)


lua-http follows the http2 convention where the status code is just another header (called :status): so no need for the extra status return value.

daurnimator · 2017-08-07T01:16:26Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+            return nil, err3
+        end
+        return {{{packagName}}}_{{classname}}.cast(result)
+    else


You can throw an error, but it's considered better practice to return nil, error, errno. Where error is usually a string, but could be some type of other object.

daurnimator · 2017-08-07T01:19:22Z

modules/swagger-codegen/src/main/resources/lua/model.mustache

+local function new_{{classname}}({{#vars}}{{name}}{{#hasMore}}, {{/hasMore}}{{/vars}})
+  return cast_pet({
+    {{#vars}}
+    {{name}} = {{name}};


For non-valid lua identifiers, the key syntax is ["f@0"]

daurnimator · 2017-08-07T01:20:28Z

samples/client/petstore/lua/lua-petstore/.gitignore

@@ -0,0 +1,40 @@
+# Compiled Lua sources


Not sure where you got this .gitignore file from.. it's tremendously broad. You probably don't need one at all..

Based on https://github.com/github/gitignore/blob/master/Lua.gitignore

daurnimator · 2017-08-07T01:21:11Z

samples/client/petstore/lua/lua-petstore/api_response.lua

+end
+
+local function new_api_response(code, type, message)
+  return cast_pet({


You left cast_pet in here.

daurnimator · 2017-08-07T01:21:57Z

samples/client/petstore/lua/lua-petstore/tag.lua

+end
+
+local function new_tag(id, name)
+  return cast_pet({


daurnimator · 2017-08-07T01:22:30Z

samples/client/petstore/lua/lua-petstore/store_api.lua

+    })
+
+    // set HTTP verb
+	req.headers:upsert(":method", "Post")


"Post" should be all caps I think?
Also this is indented oddly

daurnimator · 2017-08-07T01:22:39Z

samples/client/petstore/lua/lua-petstore/store_api.lua

+    local req = http_request.new_from_uri({
+        scheme = self.default_scheme;
+        host = self.host;
+        path = string.format("%s//store/order", self.basePath, petId);


daurnimator · 2017-08-07T01:28:48Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+local dkjson = require "dkjson"
+
+// model import
+local {{{packagName}}}_{{classname}} = require "{{{pacakgeName}}}.{{classname}}"


two different typos: pacakgeName packagName

daurnimator · 2017-08-07T01:29:06Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+local {{{packagName}}}_{{classname}} = require "{{{pacakgeName}}}.{{classname}}"
+
+local {{{packageName}}}= {}
+local {{{pacakgeName}}}_mt = {


pacakgeName

daurnimator · 2017-08-07T01:29:19Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+    })
+
+    // set HTTP verb
+	req.headers:upsert(":method", "{{httpMethod}}")


indentation

daurnimator · 2017-08-07T01:29:51Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+    local var_accept = { {{#consumes}}"{{{mediaType}}}"{{#hasMore}}, {{/hasMore}}{{/consumes}} }
+    req.headers:upsert("accept", {{#consumes}}{{#-first}}"{{{mediaType}}}"{{/-first}}{{/consumes}})
+
+    // TODO: create a function to select proper content-type


selects content-type based on what?

Here is an example for Java (jersey2):

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/resources/Java/libraries/jersey2/ApiClient.mustache#L435-L491

daurnimator · 2017-08-07T01:30:14Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+    {{/authMethods}}
+
+    // make the HTTP call
+    local headers, stream, errno = req:go()


FYI, we'll probably want to pass a timeout to :go()

OK. We can add another configurable property timeout for that.

daurnimator · 2017-08-07T04:15:41Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

@@ -91,20 +91,37 @@ function {{classname}}:{{operationId}}({{#allParams}}{{#required}}{{paramName}}{
        return nil, stream, errno
    end
    local http_status = headers:get(":status")
-    if http_status == "200" then
+    if tonumber(http_status) >= 200 or tonumber(http_status) <= 299 then


No need to convert to number (and that will have false positives, e.g. a status code of 2e2)
Instead consider if you just want to check the first character? In which case: if http_status:sub(1,1) == "2"

Sure. will update that in the next push.

daurnimator · 2017-08-07T04:19:58Z

modules/swagger-codegen/src/main/resources/lua/model.mustache

    {{#vars}}
-    {{name}} = {{name}};
+    ["{{baseName}}"] = {{name}};


Will this escape correctly if e.g. baseName include a double quote?

Also, it would be better to prefer the non-quoted form (saving the [] syntax only for invalid lua identifiers)

wing328 · 2017-08-08T14:10:06Z

I think these are the remaining items before a beta release:

add support for query parameters
add support for authentication
function to select a proper "accept", "content-type"

daurnimator · 2017-08-09T02:31:30Z

add support for query parameters

Support how?

add support for authentication

What types of auth? Does this require anything more than setting the authorization header?

function to select a proper "accept", "content-type"

When/how should this happen?

wing328 · 2017-08-09T09:13:09Z

Support how?

How can we add query parameters (URL query string) to HTTP request in Lua?

What types of auth? Does this require anything more than setting the authorization header?

HTTP basic auth, API key (header or query), OAuth access token

function to select a proper "accept", "content-type"

We need to create 2 functions in Lua similar to https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/resources/Java/libraries/jersey2/ApiClient.mustache#L435-L491

wing328 · 2017-08-10T08:08:43Z

@daurnimator I've tried to add support for query parameters and authentication via b63ab93. I also added 2 fake query parameters (will be removed before merge) to illustrate what the auto-generated Lua code for query parameters looks like.

Please review when you've time.

wing328 · 2017-08-10T08:10:33Z

Quick question: shall we put the API and model files under the sub-folder "api" and "model" respectively?

daurnimator · 2017-08-10T08:35:18Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

@@ -4,6 +4,7 @@
 {{#operations}}
 local http_request = require "http.request"
 local http_util = require "http.util"
+local url_encode = require "http.util".encodeURIComponent


No need to make this a local: call it as http_util.encodeURIComponent when needed.

daurnimator · 2017-08-10T08:36:19Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

  }, {{{packageName}}}_mt)
 end

+// for base64 encoding
+local function base64_encode(s)


Use basexx.to_base64. See https://github.com/daurnimator/lua-http/blob/master/http/request.lua#L85 for an example

daurnimator · 2017-08-10T09:51:14Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+    schemes_map[v] = v
+  end
+  local default_scheme = schemes_map.https or schemes_map.http
+  -- TODO: default basePath to {{{basePath}}}


This TODO is done.

wing328 · 2017-08-10T13:00:35Z

@daurnimator from your perspective, do you think it's ready for a beta release so as to collect more feedback from the Lua community?

daurnimator · 2017-08-10T13:25:23Z

@daurnimator from your perspective, do you think it's ready for a beta release so as to collect more feedback from the Lua community?

Maybe. Though it's not like we don't have an empty TODO list.

Other things to add:

generate a .rockspec file.
Add lua linting to .travis.yml

wing328 · 2017-08-10T13:44:53Z

Btw, something else to add would be generating a .rockspec file

I think that's for LuaRocks (lua package manager) so sure let's add that. I'll include it in the enhancement list.

daurnimator · 2017-08-10T13:45:33Z

I think that's for LuaRocks (lua package manager) so sure let's add that. I'll include it in enhancement list.

Where is this enhancement list?

wing328 · 2017-08-10T13:50:50Z

I'll create it after merging this PR into master shortly.

daurnimator · 2017-08-10T13:52:53Z

modules/swagger-codegen/src/main/resources/lua/.travis.yml

@@ -0,0 +1,8 @@
+language: go


This isn't go :)

daurnimator · 2017-08-10T13:55:20Z

modules/swagger-codegen/src/main/resources/lua/README.mustache

+{{#isApiKey}}- **Type**: API key 
+
+Example
+```


README examples need updating

Yup, I've removed the auto-genreated README for now as it needs some work to output correct examples. Will add to the enhancement list for tracking.

daurnimator · 2017-08-10T13:56:42Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+
+local {{{packageName}}}= {}
+local {{{packageName}}}_mt = {
+  __name = "{{{classname}}}";


Subjective question: indentation.
Most lua is indented in tabs or 4 spaces; however some people use 3 spaces due to it being the default in emacs; and the rare person use 8 spaces. However, 2 spaces is pretty rare.
May I suggest swapping to tabs?

Good suggestion. Is there any Lua style guide that we can follow?

I can't think of a good one :P
Even the one I wrote I don't like any more

Let's use tab then.

daurnimator · 2017-08-10T13:57:35Z

modules/swagger-codegen/src/main/resources/lua/api_response.mustache

+{{>partial_header}}
+package {{packageName}}
+
+import (


I'm not sure what this file is doing here?

Removed. (used by Go)

daurnimator · 2017-08-10T13:58:33Z

modules/swagger-codegen/src/test/resources/2_0/petstore.yaml

@@ -171,6 +171,17 @@ paths:
          required: true
          type: integer
          format: int64
+        - name: size


This needs removing before merging

Removed. Thanks for the reminder

daurnimator · 2017-08-10T13:59:59Z

modules/swagger-codegen/src/main/resources/lua/api.mustache

+    req.headers:upsert("authorization", "Bearer " .. self.access_token)
+    {{/isOAuth}}
+    {{/authMethods}}
+


There seems to be lots of whitespace in generated files around this.

It shouldn't. It's a feature in mustache template library that the following will not result in any line or whitespace

{{#thisIsFalse}} something here... {{/thisIsFalse}}

daurnimator · 2017-08-10T14:01:18Z

modules/swagger-codegen/src/main/resources/lua/.travis.yml

@@ -1,8 +1,6 @@
-language: go
+language: lua


Sadly travis doesn't support lua. Us lua devs use a tool 'hererocks' to run in travis
https://github.com/mpeterv/hererocks/#using-hererocks-to-set-up-automated-testing

Will add this to the enhancement list later

Sadly travis doesn't support lua.

Any other CI provides better support for Lua?

None I know off the top of my head. Most lua devs will just use hererocks

daurnimator · 2017-08-10T14:28:17Z

samples/client/petstore/lua/api/store_api.lua

+	--local var_accept = { "application/xml", "application/json" }
+	req.headers:upsert("content-type", "application/xml")
+
+


These are the empty lines I was talking about.

daurnimator · 2017-08-10T14:28:56Z

samples/client/petstore/lua/api/store_api.lua

+		if result == nil then
+			return nil, err3
+		end
+		return petstore_{}.cast(result), headers


petstore_{} doesn't seem like what we wanted?

Right. That method returns an array of object. Not sure how we can deserialize the result back into an array of object in Lua

It's an already an array. We might just want to cast the elements of the array to the correct type.

for _, ob in ipairs(result) do cast_pet(ob) end

OK. What if the result is a dictionary/hash/map? What should the code look like?

Hrm? a dictionary/hash of what?
dkjson.decode will just decode the json object and return a lua table (arrays and dictionaries are the same data structure in lua)

dkjson.decode will just decode the json object and return a lua table

That should work.

Hrm? a dictionary/hash of what?

Here is an example (the key is not fixed):
{
"cat" : 10,
"dog": 2,
"rabbit": 7
}

wing328 · 2017-08-10T15:13:54Z

samples/client/petstore/lua/api/pet_api.lua

+		if result == nil then
+			return nil, err3
+		end
+		return petstore_pet.cast(result), headers


@daurnimator should this be cast_pet(result), headers?

Updated to use cast_pet via 6d180af

wing328 · 2017-08-10T17:50:34Z

Tweet: https://twitter.com/wing328/status/895703684079734784 to promote the new generator.

wing328 · 2017-08-10T18:02:52Z

@daurnimator here is the enhancement list: #6284

wing328 · 2017-08-10T18:06:04Z

Add @daurnimator as the template creator of Lua via f4de426

wing328 added 2 commits August 6, 2017 16:21

1st commit of lua generator

c63727e

add petstore sample

c8d65cf

wing328 added Client: Lua Enhancement: New generator labels Aug 6, 2017

wing328 added this to the v2.3.0 milestone Aug 6, 2017

wing328 commented Aug 6, 2017

View reviewed changes

daurnimator suggested changes Aug 7, 2017

View reviewed changes

daurnimator reviewed Aug 7, 2017

View reviewed changes

wing328 added 2 commits August 7, 2017 11:09

various fixes based on feedback

76a2368

better return handling

436c5e6

daurnimator reviewed Aug 7, 2017

View reviewed changes

check status code 1st letter

59b110f

add support for query parameters, auth, body param

b63ab93

daurnimator reviewed Aug 10, 2017

View reviewed changes

more fixes based on feedback

0bb3c33

daurnimator reviewed Aug 10, 2017

View reviewed changes

modules/swagger-codegen/src/main/resources/lua/.travis.yml Outdated

@@ -0,0 +1,8 @@

language: go

Copy link

Contributor

daurnimator Aug 10, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't go :)

update lua sample

3ab8cdb

daurnimator reviewed Aug 10, 2017

View reviewed changes

skip auto-generated readme, doc, test files

95bd5b7

daurnimator reviewed Aug 10, 2017

View reviewed changes

use tab instead of 2-space

aee852d

daurnimator reviewed Aug 10, 2017

View reviewed changes

wing328 added 2 commits August 10, 2017 23:04

fix container return type

17a4403

fix cast method call

e1284e0

wing328 commented Aug 10, 2017

View reviewed changes

fix cast function call

6d180af

wing328 merged commit 06686d6 into master Aug 10, 2017

wing328 mentioned this pull request Aug 10, 2017

[Lua] Enhancements to Lua generator #6284

Open

8 tasks

wing328 mentioned this pull request Aug 11, 2017

[Lua] Add API client generation #4794

Closed

wing328 deleted the lua_generator branch August 17, 2017 06:18

		--local var_accept = { "application/xml", "application/json" }
		req.headers:upsert("content-type", "application/xml")

[Lua] Add new Lua client generator #6252

[Lua] Add new Lua client generator #6252

Conversation

wing328 commented Aug 6, 2017 • edited Loading

PR checklist

Description of the PR

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wing328 commented Aug 6, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wing328 commented Aug 8, 2017

daurnimator commented Aug 9, 2017

wing328 commented Aug 9, 2017

wing328 commented Aug 10, 2017

wing328 commented Aug 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wing328 commented Aug 10, 2017

daurnimator commented Aug 10, 2017 • edited Loading

wing328 commented Aug 10, 2017 • edited Loading

daurnimator commented Aug 10, 2017

wing328 commented Aug 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

daurnimator Aug 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wing328 commented Aug 6, 2017 •

edited

Loading

daurnimator commented Aug 10, 2017 •

edited

Loading

wing328 commented Aug 10, 2017 •

edited

Loading

daurnimator Aug 10, 2017 •

edited

Loading