-
-
Notifications
You must be signed in to change notification settings - Fork 6.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add auto-generated doc to Swift4 generator #2666
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍
// 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- The initializer should have labels for parameters.
- It looks
Bool
turnsInt
, should betrue
orfalse
.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Date is standard struct in Swift
**byte** | [**Data**](Data.md) | | | ||
**binary** | [**URL**](URL.md) | | [optional] | ||
**date** | [**Date**](Date.md) | | | ||
**dateTime** | [**Date**](Date.md) | | [optional] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as above
**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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
**URL****URL**
should be **URL**
|
||
Name | Type | Description | Notes | ||
------------- | ------------- | ------------- | ------------- | ||
**param** | [**[String:String]**](String.md)| request body | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
String.md should not be refer.
Name | Type | Description | Notes | ||
------------- | ------------- | ------------- | ------------- | ||
**param** | **String**| field1 | | ||
**param2** | **String**| field2 | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should not refer Dictionary.md
## Properties | ||
Name | Type | Description | Notes | ||
------------ | ------------- | ------------- | ------------- | ||
**arrayArrayNumber** | [**[[Double]]**](Array.md) | | [optional] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should not refer Array.md
------------ | ------------- | ------------- | ------------- | ||
**arrayOfString** | **[String]** | | [optional] | ||
**arrayArrayOfInteger** | [**[[Int64]]**](Array.md) | | [optional] | ||
**arrayArrayOfModel** | [**[[ReadOnlyFirst]]**](Array.md) | | [optional] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Array.md
|
||
# **fakeOuterBooleanSerialize** | ||
```swift | ||
open class func fakeOuterBooleanSerialize( body: Bool? = nil) -> Promise<Bool> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Datetime is also.
let datetime = Date() // means now.
|
||
Name | Type | Description | Notes | ||
------------- | ------------- | ------------- | ------------- | ||
**param** | [**[String:String]**](String.md)| request body | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
String.md)
|
||
### Return type | ||
|
||
void (empty response body) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.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\
.master
,. Default:3.4.x
,4.0.x
master
.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)