Add auto-generated doc to Swift4 generator #2666
Conversation
| // 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 |
There was a problem hiding this comment.
- The initializer should have labels for parameters.
- It looks
BoolturnsInt, should betrueorfalse.
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)
| } | ||
| {{/usePromiseKit}} | ||
| {{#useRxSwift}} | ||
| // TODO rxswift sample code. To contribute, please open a ticket via http://github.com/OpenAPITools/openapi-generator/issues/new |
There was a problem hiding this comment.
If indent is not match, please indent with 4 spaces
| // 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) | |
| } |
| **float** | **Float** | | [optional] | ||
| **double** | **Double** | | [optional] | ||
| **string** | **String** | | [optional] | ||
| **byte** | [**Data**](Data.md) | | |
There was a problem hiding this comment.
Data is standard struct in Swift.
| **double** | **Double** | | [optional] | ||
| **string** | **String** | | [optional] | ||
| **byte** | [**Data**](Data.md) | | | ||
| **binary** | [**URL**](URL.md) | | [optional] |
There was a problem hiding this comment.
URL is standard struct in Swift
| **string** | **String** | | [optional] | ||
| **byte** | [**Data**](Data.md) | | | ||
| **binary** | [**URL**](URL.md) | | [optional] | ||
| **date** | [**Date**](Date.md) | | |
There was a problem hiding this comment.
Date is standard struct in Swift
| **byte** | [**Data**](Data.md) | | | ||
| **binary** | [**URL**](URL.md) | | [optional] | ||
| **date** | [**Date**](Date.md) | | | ||
| **dateTime** | [**Date**](Date.md) | | [optional] |
| **binary** | [**URL**](URL.md) | | [optional] | ||
| **date** | [**Date**](Date.md) | | | ||
| **dateTime** | [**Date**](Date.md) | | [optional] | ||
| **uuid** | [**UUID**](UUID.md) | | [optional] |
There was a problem hiding this comment.
UUID is struct in Foundation, no need to reference.
| **mapArrayAnytype** | [**[String:[Any]]**](Array.md) | | [optional] | ||
| **mapMapString** | [**[String:[String:String]]**](Dictionary.md) | | [optional] | ||
| **mapMapAnytype** | [**[String:[String:Any]]**](Dictionary.md) | | [optional] | ||
| **anytype1** | [**Any**](.md) | | [optional] |
There was a problem hiding this comment.
Any is primitive type in Swift
| ------------ | ------------- | ------------- | ------------- | ||
| **arrayOfString** | **[String]** | | [optional] | ||
| **arrayArrayOfInteger** | [**[[Int64]]**](Array.md) | | [optional] | ||
| **arrayArrayOfModel** | [**[[ReadOnlyFirst]]**](Array.md) | | [optional] |
There was a problem hiding this comment.
should not refer to Array.md, but ReadOnlyFirst.md.
|
|
||
| Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 | ||
|
|
||
| Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 |
There was a problem hiding this comment.
Is it correct to be printed out same comments?
| **int64** | **Int64**| None | [optional] | ||
| **float** | **Float**| None | [optional] | ||
| **string** | **String**| None | [optional] | ||
| **binary** | **URL****URL**| None | [optional] |
There was a problem hiding this comment.
**URL****URL** should be **URL**
|
|
||
| Name | Type | Description | Notes | ||
| ------------- | ------------- | ------------- | ------------- | ||
| **param** | [**[String:String]**](String.md)| request body | |
There was a problem hiding this comment.
String.md should not be refer.
| Name | Type | Description | Notes | ||
| ------------- | ------------- | ------------- | ------------- | ||
| **param** | **String**| field1 | | ||
| **param2** | **String**| field2 | |
There was a problem hiding this comment.
[NIT] should have space after **String**
| Name | Type | Description | Notes | ||
| ------------ | ------------- | ------------- | ------------- | ||
| **mapString** | **[String:String]** | | [optional] | ||
| **mapMapString** | [**[String:[String:String]]**](Dictionary.md) | | [optional] |
There was a problem hiding this comment.
Should not refer Dictionary.md
| ## Properties | ||
| Name | Type | Description | Notes | ||
| ------------ | ------------- | ------------- | ------------- | ||
| **arrayArrayNumber** | [**[[Double]]**](Array.md) | | [optional] |
| ------------ | ------------- | ------------- | ------------- | ||
| **arrayOfString** | **[String]** | | [optional] | ||
| **arrayArrayOfInteger** | [**[[Int64]]**](Array.md) | | [optional] | ||
| **arrayArrayOfModel** | [**[[ReadOnlyFirst]]**](Array.md) | | [optional] |
|
|
||
| # **fakeOuterBooleanSerialize** | ||
| ```swift | ||
| open class func fakeOuterBooleanSerialize( body: Bool? = nil) -> Promise<Bool> |
There was a problem hiding this comment.
[NIT] should be removed space before parameter
| 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) |
There was a problem hiding this comment.
URL example is like below. String should be more exampled.
let binary = URL(string: "https://example.com")!
| 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) |
There was a problem hiding this comment.
Date example is like below.
let date = Date() // means now.
| 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) |
There was a problem hiding this comment.
Datetime is also.
let datetime = Date() // means now.
|
|
||
| Name | Type | Description | Notes | ||
| ------------- | ------------- | ------------- | ------------- | ||
| **param** | [**[String:String]**](String.md)| request body | |
|
|
||
| ### Return type | ||
|
|
||
| void (empty response body) |
There was a problem hiding this comment.
type name void should be capitalized Void .
|
|
||
| To test class name in snake case | ||
|
|
||
| To test class name in snake case |
There was a problem hiding this comment.
I think some pattern has duplicated comments
|
|
||
| # **getOrderById** | ||
| ```swift | ||
| open class func getOrderById(orderId: Int64, completion: @escaping ((_ data: Order?,_ error: Error?) -> Void)) |
There was a problem hiding this comment.
should be
- single bracket for closure
- [NIT] need space after comma
open class func getOrderById(orderId: Int64, completion: @escaping (_ data: Order?, _ error: Error?) -> Void)
|
I believe that all for review, but if you need to be more checked, let me know. |
|
Thanks for the review 👍 Let me fix those. |
|
I should have fixed most if not all of the reviews. About the duplicated description, it's due to both |
|
Let's go with this one and we can always submit another PR to further improve the doc. |
PR checklist
./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.shif 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\.master,. Default:3.4.x,4.0.xmaster.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)