Skip to content

Commit acede28

Browse files
GoutteGoutte
committed
chore(gdscript): review, document, clean up
/spend 2h
1 parent edce567 commit acede28

File tree

13 files changed

+143
-195
lines changed

13 files changed

+143
-195
lines changed

‎modules/openapi-generator/src/main/resources/gdscript/README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,13 @@ Godot does not have an `Exception` (`try / catch`) mechanism, by design.
2929
Therefore, whenever there's trouble in paradise, we pass around an `ApiError` object. (a `RefCounted`, don't worry about garbage collection)
3030

3131

32-
## AoiResponse
32+
### AoiResponse
3333

34-
A wrapper for an Api response, used in callbacks.
35-
Holds the HTTP components of a Response, as well as the deserialized data (if any).
34+
A wrapper for an Api Response, used in callbacks.
35+
Holds the HTTP components of the Response, as well as the deserialized `data` (if any).
36+
37+
38+
## Extending
39+
40+
Most classes can be configured to extend your own class.
41+
Override the `partials/*_parent_class.handlebars` to define them.

‎modules/openapi-generator/src/main/resources/gdscript/core/ApiBee.handlebars‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,8 @@ func _bzz_request(
174174
var error := {{>partials/api_error_class_name}}.new()
175175
error.internal_code = parsing
176176
error.identifier = "apibee.decode.cannot_parse_json"
177+
error.response_code = response.code
178+
error.response = response
177179
error.message = "%s: failed to parse JSON response at line %d.\n%s" % [
178180
_bzz_name, parser.get_error_line(), parser.get_error_message()
179181
]
@@ -184,6 +186,8 @@ func _bzz_request(
184186
var error := {{>partials/api_error_class_name}}.new()
185187
error.internal_code = ERR_INVALID_DATA
186188
error.identifier = "apibee.decode.mime_type_unsupported"
189+
error.response_code = response.code
190+
error.response = response
187191
error.message = "%s: mime type `%s' is not supported (yet -- MRs welcome)" % [
188192
_bzz_name, mime
189193
]
@@ -350,6 +354,7 @@ func _bzz_do_request_text(
350354
var error := {{>partials/api_error_class_name}}.new()
351355
error.internal_code = ERR_PRINTER_ON_FIRE
352356
error.response_code = response.code
357+
error.response = response
353358
error.identifier = "apibee.response.5xx"
354359
error.message = "%s: request to `%s' made the server hiccup with a %d." % [
355360
_bzz_name, path, response.code
@@ -363,6 +368,7 @@ func _bzz_do_request_text(
363368
var error := {{>partials/api_error_class_name}}.new()
364369
error.identifier = "apibee.response.4xx"
365370
error.response_code = response.code
371+
error.response = response
366372
error.message = "%s: request to `%s' was denied with a %d." % [
367373
_bzz_name, path, response.code
368374
]
@@ -375,6 +381,7 @@ func _bzz_do_request_text(
375381
var error := {{>partials/api_error_class_name}}.new()
376382
error.identifier = "apibee.response.3xx"
377383
error.response_code = response.code
384+
error.response = response
378385
error.message = "%s: request to `%s' was redirected with a %d. We do not support redirects in that client yet." % [
379386
_bzz_name, path, response.code
380387
]

‎modules/openapi-generator/src/main/resources/gdscript/core/ApiConfig.handlebars‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,21 @@
1-
extends Resource
1+
extends {{>partials/api_config_parent_class}}
22
class_name {{>partials/api_config_class_name}}
33

44
{{>partials/disclaimer_autogenerated}}
55

6-
76
# Configuration options for Api endpoints
87
# =======================================
98
#
109
# Helps share configuration customizations across Apis:
1110
# - host, port & scheme
12-
# - extra headers
13-
# - security layer options (TLS certificates)
11+
# - extra headers (low priority, high priority)
12+
# - transport layer security options (TLS certificates)
1413
# - log level
1514
#
1615
# You probably want to make an instance of this class with your own values,
17-
# and feed it to each Api's `bee_config` before calling the Api's methods.
16+
# and feed it to each Api's constructor, before calling the Api's methods.
1817
#
19-
# Since it is a Resource, you may use `ResourceSaver.save()` and `load()`
18+
# Since it is a Resource, you may use `ResourceSaver.save()` and `preload()`
2019
# to save it and load it from file, for convenience.
2120
#
2221

@@ -45,7 +44,7 @@ enum LogLevel {
4544

4645
{{!--
4746
# Not sure if this should hold the HTTPClient instance or not. Not for now.
48-
# Godot recommends using a single client for all requests, so it should.
47+
# Godot recommends using a single client for all requests, so it perhaps should.
4948
5049
# Godot's HTTP Client we are using.
5150
# If none was set (by you), we'll lazily make one.

‎modules/openapi-generator/src/main/resources/gdscript/core/ApiError.handlebars‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,41 @@
1-
extends Resource
1+
extends {{>partials/api_error_parent_class}}
22
class_name {{>partials/api_error_class_name}}
33

4+
{{>partials/disclaimer_autogenerated}}
5+
6+
# Error wrapper provided to error callbacks
7+
# =========================================
8+
#
9+
# Whenever this OAS client fails to comply to your request, for any reason,
10+
# it will trigger the error callback, with an instance of this as parameter.
11+
#
12+
413
# Helps finding the error in the code, among other things.
514
# Could be a UUID, or even a translation key, so long as it's unique.
15+
# Right now we're mostly using a lowercase ~namespace joined by dots. (.)
616
@export var identifier := ""
717

818
# A message for humans. May be multiline.
919
@export var message := ""
1020

11-
# One of Godot's ERR_XXXX when relevant
21+
# One of Godot's ERR_XXXX, when relevant.
1222
@export var internal_code := OK
1323

1424
# The HTTP response code, if any. (usually >= 400)
25+
# DEPRECATED: prefer reading from response object below
1526
@export var response_code := HTTPClient.RESPONSE_OK
1627

28+
# The HTTP response, if any.
29+
@export var response: {{>partials/api_response_class_name}}
1730

18-
func _to_string() -> String:
19-
var s := ""
2031

32+
func _to_string() -> String:
33+
var s := "{{>partials/api_error_class_name}}"
2134
if identifier:
22-
s += "%s\n" % identifier
35+
s += " %s" % identifier
2336
if message:
24-
s += "%s\n" % message
25-
37+
s += " %s" % message
38+
if response:
39+
s += "\n%s" % str(response)
2640
return s
2741

‎modules/openapi-generator/src/main/resources/gdscript/core/ApiResponse.handlebars‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,31 @@
11
extends {{>partials/api_response_parent_class}}
22
class_name {{>partials/api_response_class_name}}
33

4-
# Headers sent back by the server
5-
var headers := Dictionary()
4+
{{>partials/disclaimer_autogenerated}}
65

7-
# Raw body of this response, in String form (before deserialization)
8-
var body := ""
6+
# Response wrapper provided to success callbacks
7+
# ==============================================
8+
#
9+
# Holds the response metadata, its body, and the deserialized model(s), if any.
10+
# This object is directly passed to the success callback, and in case of failure
11+
# is injected in the error object.
12+
#
13+
14+
# Headers sent back by the server
15+
@export var headers := Dictionary()
916

1017
# The HTTP response code, if any. A constant like HTTPClient.RESPONSE_XXXX
11-
var code := 0
18+
@export var code := 0
19+
20+
# Raw body of this response, in String form (before deserialization)
21+
@export var body := ""
1222

1323
# Deserialized body (may be pretty much any type)
1424
var data
1525

1626

1727
func _to_string() -> String:
18-
var s := "ApiResponse"
28+
var s := "{{>partials/api_response_class_name}}"
1929
if code:
2030
s += " %d" % code
2131
if body:

‎modules/openapi-generator/src/main/resources/gdscript/partials/api_config_parent_class.handlebars‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{!--
2+
Override this template to let config inherit from your own desired class.
3+
It's probably best to use a descendant of Resource here (@export is used).
4+
TODO: would be neat to be able to customize this parent class from CLI.
5+
--}}
6+
Resource

‎modules/openapi-generator/src/main/resources/gdscript/partials/api_error_parent_class.handlebars‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{{!--
2+
Override this template to let error inherit from your own desired class.
3+
It's probably best to use a descendant of Resource here (@export is used).
4+
TODO: would be cool to be able to customize this parent class from CLI.
5+
--}}
6+
Resource

‎modules/openapi-generator/src/main/resources/gdscript/partials/api_response_parent_class.handlebars‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1+
{{!--
2+
Override this template to let response inherit from your own desired class.
3+
It's probably best to use a descendant of Resource here (@export is used).
4+
TODO: would be cool to be able to customize this parent class from CLI.
5+
--}}
16
Resource

‎samples/client/petstore/gdscript/addons/oas.petstore.client/core/DemoApiConfig.gd‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,19 @@ class_name DemoApiConfig
77
# https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/gdscript
88
# The OpenAPI Generator Community, © Public Domain, 2022
99

10-
1110
# Configuration options for Api endpoints
1211
# =======================================
1312
#
1413
# Helps share configuration customizations across Apis:
1514
# - host, port & scheme
16-
# - extra headers
17-
# - security layer options (TLS certificates)
15+
# - extra headers (low priority, high priority)
16+
# - transport layer security options (TLS certificates)
1817
# - log level
1918
#
2019
# You probably want to make an instance of this class with your own values,
21-
# and feed it to each Api's `bee_config` before calling the Api's methods.
20+
# and feed it to each Api's constructor, before calling the Api's methods.
2221
#
23-
# Since it is a Resource, you may use `ResourceSaver.save()` and `load()`
22+
# Since it is a Resource, you may use `ResourceSaver.save()` and `preload()`
2423
# to save it and load it from file, for convenience.
2524
#
2625

‎samples/client/petstore/gdscript/addons/oas.petstore.client/core/DemoApiError.gd‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,45 @@
11
extends Resource
22
class_name DemoApiError
33

4+
# THIS FILE WAS AUTOMATICALLY GENERATED by the OpenAPI Generator project.
5+
# For more information on how to customize templates, see:
6+
# https://openapi-generator.tech
7+
# https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/gdscript
8+
# The OpenAPI Generator Community, © Public Domain, 2022
9+
10+
# Error wrapper provided to error callbacks
11+
# =========================================
12+
#
13+
# Whenever this OAS client fails to comply to your request, for any reason,
14+
# it will trigger the error callback, with an instance of this as parameter.
15+
#
16+
417
# Helps finding the error in the code, among other things.
518
# Could be a UUID, or even a translation key, so long as it's unique.
19+
# Right now we're mostly using a lowercase ~namespace joined by dots. (.)
620
@export var identifier := ""
721

822
# A message for humans. May be multiline.
923
@export var message := ""
1024

11-
# One of Godot's ERR_XXXX when relevant
25+
# One of Godot's ERR_XXXX, when relevant.
1226
@export var internal_code := OK
1327

1428
# The HTTP response code, if any. (usually >= 400)
29+
# DEPRECATED: prefer reading from response object below
1530
@export var response_code := HTTPClient.RESPONSE_OK
1631

32+
# The HTTP response, if any.
33+
@export var response: DemoApiResponse
1734

18-
func _to_string() -> String:
19-
var s := ""
2035

36+
func _to_string() -> String:
37+
var s := "DemoApiError"
2138
if identifier:
22-
s += "%s\n" % identifier
39+
s += " %s" % identifier
2340
if message:
24-
s += "%s\n" % message
25-
41+
s += " %s" % message
42+
if response:
43+
s += "\n%s" % str(response)
2644
return s
2745

0 commit comments

Comments
 (0)