Add auto-generated doc to Swift4 generator by wing328 · Pull Request #2666 · OpenAPITools/openapi-generator

wing328 · 2019-04-15T13:52:29Z

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, ./bin/openapi3/{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~~, 3.4.x, 4.0.x~~. Default: master.
Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

Add auto-generated documentation (README, API doc, model doc) to Swift4 generator

@jgavris (2017/07) @ehyche (2017/08) @Edubits (2017/09) @jaz-ah (2017/09) @d-date (2018/03)

d-date

👍

d-date · 2019-04-15T17:32:42Z

+// the following code samples are still beta. If you notice any issue, please report via http://github.com/OpenAPITools/openapi-generator/issues/new
+import PetstoreClient
+
+let body = Order(123, 123, 123, "TODO", "status_example", 123) // Order | order placed for purchasing the pet


The initializer should have labels for parameters.

It looks Bool turns Int, should be true or false.

As is:

let body = Order(123, 123, 123, "TODO", "status_example", 123)

Ideal:

let body = Order(id: 123, petId: 123, quantity: 123, shipDate: "TODO", status: "status_example", complete: true)

d-date · 2019-04-15T17:45:15Z

+}
+{{/usePromiseKit}}
+{{#useRxSwift}}
+// TODO rxswift sample code. To contribute, please open a ticket via http://github.com/OpenAPITools/openapi-generator/issues/new


If indent is not match, please indent with 4 spaces

Suggested change

// TODO rxswift sample code. To contribute, please open a ticket via http://github.com/OpenAPITools/openapi-generator/issues/new

{{#summary}}// {{{.}}}

{{/summary}}{{classname}}.{{{operationId}}}({{#allParams}}{{paramName}}: {{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}}).subscribe(onNext: {

// when request is on success

}, onError: { error in

// when request was failed with error

}).disposed(by: disposeBag)

}

d-date · 2019-04-15T17:49:00Z

+**float** | **Float** |  | [optional] 
+**double** | **Double** |  | [optional] 
+**string** | **String** |  | [optional] 
+**byte** | [**Data**](Data.md) |  | 


Data is standard struct in Swift.

d-date · 2019-04-15T17:49:14Z

+**double** | **Double** |  | [optional] 
+**string** | **String** |  | [optional] 
+**byte** | [**Data**](Data.md) |  | 
+**binary** | [**URL**](URL.md) |  | [optional] 


URL is standard struct in Swift

d-date · 2019-04-15T17:49:27Z

+**string** | **String** |  | [optional] 
+**byte** | [**Data**](Data.md) |  | 
+**binary** | [**URL**](URL.md) |  | [optional] 
+**date** | [**Date**](Date.md) |  | 


Date is standard struct in Swift

d-date · 2019-04-15T17:49:42Z

+**byte** | [**Data**](Data.md) |  | 
+**binary** | [**URL**](URL.md) |  | [optional] 
+**date** | [**Date**](Date.md) |  | 
+**dateTime** | [**Date**](Date.md) |  | [optional] 


Same as above

d-date · 2019-04-15T17:50:39Z

+**binary** | [**URL**](URL.md) |  | [optional] 
+**date** | [**Date**](Date.md) |  | 
+**dateTime** | [**Date**](Date.md) |  | [optional] 
+**uuid** | [**UUID**](UUID.md) |  | [optional] 


UUID is struct in Foundation, no need to reference.

d-date · 2019-04-15T17:52:43Z

+**mapArrayAnytype** | [**[String:[Any]]**](Array.md) |  | [optional] 
+**mapMapString** | [**[String:[String:String]]**](Dictionary.md) |  | [optional] 
+**mapMapAnytype** | [**[String:[String:Any]]**](Dictionary.md) |  | [optional] 
+**anytype1** | [**Any**](.md) |  | [optional] 


Any is primitive type in Swift

d-date · 2019-04-15T17:53:54Z

+------------ | ------------- | ------------- | -------------
+**arrayOfString** | **[String]** |  | [optional] 
+**arrayArrayOfInteger** | [**[[Int64]]**](Array.md) |  | [optional] 
+**arrayArrayOfModel** | [**[[ReadOnlyFirst]]**](Array.md) |  | [optional] 


should not refer to Array.md, but ReadOnlyFirst.md.

d-date · 2019-04-15T17:56:50Z

+
+Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
+
+Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 


Is it correct to be printed out same comments?

d-date · 2019-04-15T17:57:17Z

+ **int64** | **Int64**| None | [optional] 
+ **float** | **Float**| None | [optional] 
+ **string** | **String**| None | [optional] 
+ **binary** | **URL****URL**| None | [optional] 


**URL****URL** should be **URL**

d-date · 2019-04-15T17:58:06Z

+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **param** | [**[String:String]**](String.md)| request body | 


String.md should not be refer.

d-date · 2019-04-15T17:58:38Z

+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **param** | **String**| field1 | 
+ **param2** | **String**| field2 | 


[NIT] should have space after **String**

d-date · 2019-04-15T18:02:41Z

+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**mapString** | **[String:String]** |  | [optional] 
+**mapMapString** | [**[String:[String:String]]**](Dictionary.md) |  | [optional] 


Should not refer Dictionary.md

d-date · 2019-04-15T18:03:09Z

+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**arrayArrayNumber** | [**[[Double]]**](Array.md) |  | [optional] 


Should not refer Array.md

d-date · 2019-04-15T18:03:21Z

+------------ | ------------- | ------------- | -------------
+**arrayOfString** | **[String]** |  | [optional] 
+**arrayArrayOfInteger** | [**[[Int64]]**](Array.md) |  | [optional] 
+**arrayArrayOfModel** | [**[[ReadOnlyFirst]]**](Array.md) |  | [optional] 


d-date · 2019-04-15T18:04:04Z

+
+# **fakeOuterBooleanSerialize**
+```swift
+    open class func fakeOuterBooleanSerialize( body: Bool? = nil) -> Promise<Bool>


[NIT] should be removed space before parameter

d-date · 2019-04-15T18:06:05Z

+let int64 = 987 // Int64 | None (optional)
+let float = 987 // Float | None (optional)
+let string = "string_example" // String | None (optional)
+let binary = "TODO" // URL | None (optional)


URL example is like below. String should be more exampled.

let binary = URL(string: "https://example.com")!

d-date · 2019-04-15T18:06:57Z

+let float = 987 // Float | None (optional)
+let string = "string_example" // String | None (optional)
+let binary = "TODO" // URL | None (optional)
+let date = TODO // Date | None (optional)


Date example is like below.

let date = Date() // means now.

d-date · 2019-04-15T18:07:26Z

+let string = "string_example" // String | None (optional)
+let binary = "TODO" // URL | None (optional)
+let date = TODO // Date | None (optional)
+let dateTime = TODO // Date | None (optional)


Datetime is also.

let datetime = Date() // means now.

d-date · 2019-04-15T18:08:30Z

+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **param** | [**[String:String]**](String.md)| request body | 


d-date · 2019-04-15T18:09:24Z

+
+### Return type
+
+void (empty response body)


type name void should be capitalized Void .

d-date · 2019-04-15T18:09:52Z

+
+To test class name in snake case
+
+To test class name in snake case


I think some pattern has duplicated comments

d-date · 2019-04-15T18:14:33Z

+
+# **getOrderById**
+```swift
+    open class func getOrderById(orderId: Int64, completion: @escaping ((_ data: Order?,_ error: Error?) -> Void))


should be

single bracket for closure

[NIT] need space after comma

open class func getOrderById(orderId: Int64, completion: @escaping (_ data: Order?, _ error: Error?) -> Void)

d-date · 2019-04-15T18:16:51Z

I believe that all for review, but if you need to be more checked, let me know.

wing328 · 2019-04-16T03:30:17Z

Thanks for the review 👍

Let me fix those.

wing328 · 2019-04-16T07:36:13Z

I should have fixed most if not all of the reviews.

About the duplicated description, it's due to both summary and notes set to the same description text.

wing328 · 2019-04-16T08:55:22Z

Let's go with this one and we can always submit another PR to further improve the doc.

add auto-generated doc to swift4 generators

2c235ad

wing328 added Client: Swift Enhancement: Feature Feature: Documentation labels Apr 15, 2019

wing328 added this to the 4.0.0 milestone Apr 15, 2019

d-date approved these changes Apr 15, 2019

View reviewed changes

fix rxswift sample code

906bdb6

d-date reviewed Apr 15, 2019

View reviewed changes

wing328 added 7 commits April 16, 2019 11:53

fix object initialize

05f86bc

fix boolean value

1a0b5bb

fix link to object

be56c29

fix void

6b0a96a

fix url initialize

f2d5a4e

update all swift samples

718b729

fix indentation

818c89c

wing328 merged commit 4b84821 into master Apr 16, 2019

wing328 deleted the swift-auto-doc branch April 16, 2019 08:55

lemoinem mentioned this pull request May 21, 2019

[BUG][Swift4] StackOverflow when generating example for recursive structures #2966

Closed

5 tasks

-// TODO rxswift sample code. To contribute, please open a ticket via http://github.com/OpenAPITools/openapi-generator/issues/new
+{{#summary}}// {{{.}}}
+{{/summary}}{{classname}}.{{{operationId}}}({{#allParams}}{{paramName}}: {{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}}).subscribe(onNext: {
+        // when request is on success
+    }, onError: { error in
+        // when request was failed with error
+    }).disposed(by: disposeBag)
+}


		Fake endpoint for testing various parameters 假端點偽のエンドポイント 가짜 엔드 포인트

		Fake endpoint for testing various parameters 假端點偽のエンドポイント 가짜 엔드 포인트


		To test class name in snake case

		To test class name in snake case

Uh oh!

Conversation

wing328 commented Apr 15, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR checklist

Description of the PR

Uh oh!

d-date left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-date Apr 15, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-date Apr 15, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-date commented Apr 15, 2019

Uh oh!

wing328 commented Apr 16, 2019

Uh oh!

wing328 commented Apr 16, 2019

Uh oh!

wing328 commented Apr 16, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wing328 commented Apr 15, 2019 •

edited

Loading

d-date Apr 15, 2019 •

edited

Loading

d-date Apr 15, 2019 •

edited

Loading