Fixed Python client docstrings (#6780)

* Updated api_client and configuration docstrings ApiClient: Removed host param, added configuration and cookie param Configuration: Docstrings are only read from the @property decorated function, not the setter, moved the more descriptive docstrings from the setters to property functions * Ran bin/python-petstore.sh
2017-10-23 06:44:37 -04:00
parent 18b16c7fe6
commit c6b6249f1c
7 changed files with 203 additions and 56 deletions
--- a/modules/swagger-codegen/src/main/resources/python/api_client.mustache
+++ b/modules/swagger-codegen/src/main/resources/python/api_client.mustache
@@ -36,9 +36,12 @@ class ApiClient(object):
    Ref: https://github.com/swagger-api/swagger-codegen
    Do not edit the class manually.

-    :param host: The base path for the server to call.
+    :param configuration: .Configuration object for this client
    :param header_name: a header to pass when making calls to the API.
-    :param header_value: a header value to pass when making calls to the API.
+    :param header_value: a header value to pass when making calls to 
+        the API.
+    :param cookie: a cookie to include in the header when making calls 
+        to the API
    """

    PRIMITIVE_TYPES = (float, bool, bytes, text_type) + integer_types
@@ -73,16 +76,11 @@ class ApiClient(object):

    @property
    def user_agent(self):
-        """
-        Gets user agent.
-        """
+        """User agent for this API client"""
        return self.default_headers['User-Agent']

    @user_agent.setter
    def user_agent(self, value):
-        """
-        Sets user agent.
-        """
        self.default_headers['User-Agent'] = value

    def set_default_header(self, header_name, header_value):
--- a/modules/swagger-codegen/src/main/resources/python/configuration.mustache
+++ b/modules/swagger-codegen/src/main/resources/python/configuration.mustache
@@ -100,15 +100,19 @@ class Configuration(with_metaclass(TypeWithDefault, object)):

    @property
    def logger_file(self):
-        """
-        Gets the logger_file.
+        """The logger file.
+
+        If the logger_file is None, then add stream handler and remove file handler.
+        Otherwise, add file handler and remove stream handler.
+
+        :param value: The logger_file path.
+        :type: str
        """
        return self.__logger_file

    @logger_file.setter
    def logger_file(self, value):
-        """
-        Sets the logger_file.
+        """The logger file.

        If the logger_file is None, then add stream handler and remove file handler.
        Otherwise, add file handler and remove stream handler.
@@ -138,15 +142,16 @@ class Configuration(with_metaclass(TypeWithDefault, object)):

    @property
    def debug(self):
-        """
-        Gets the debug status.
+        """Debug status
+
+        :param value: The debug status, True or False.
+        :type: bool
        """
        return self.__debug

    @debug.setter
    def debug(self, value):
-        """
-        Sets the debug status.
+        """Debug status

        :param value: The debug status, True or False.
        :type: bool
@@ -168,15 +173,18 @@ class Configuration(with_metaclass(TypeWithDefault, object)):

    @property
    def logger_format(self):
-        """
-        Gets the logger_format.
+        """The logger format.
+
+        The logger_formatter will be updated when sets logger_format.
+
+        :param value: The format string.
+        :type: str
        """
        return self.__logger_format

    @logger_format.setter
    def logger_format(self, value):
-        """
-        Sets the logger_format.
+        """The logger format.

        The logger_formatter will be updated when sets logger_format.

@@ -187,8 +195,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
        self.logger_formatter = logging.Formatter(self.__logger_format)

    def get_api_key_with_prefix(self, identifier):
-        """
-        Gets API key (with prefix if set).
+        """Gets API key (with prefix if set).

        :param identifier: The identifier of apiKey.
        :return: The token for api key authentication.
@@ -199,8 +206,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
            return self.api_key[identifier]

    def get_basic_auth_token(self):
-        """
-        Gets HTTP basic authentication header (string).
+        """Gets HTTP basic authentication header (string).

        :return: The token for basic HTTP authentication.
        """
@@ -208,8 +214,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
                           .get('authorization')

    def auth_settings(self):
-        """
-        Gets Auth Settings dict for api client.
+        """Gets Auth Settings dict for api client.

        :return: The Auth Settings information dict.
        """
@@ -244,8 +249,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
        }

    def to_debug_report(self):
-        """
-        Gets the essential information for debugging.
+        """Gets the essential information for debugging.

        :return: The report for debugging.
        """
--- a/samples/client/petstore/python/README.md
+++ b/samples/client/petstore/python/README.md
@@ -77,6 +77,7 @@ Class | Method | HTTP request | Description
 *FakeApi* | [**test_client_model**](docs/FakeApi.md#test_client_model) | **PATCH** /fake | To test \&quot;client\&quot; model
 *FakeApi* | [**test_endpoint_parameters**](docs/FakeApi.md#test_endpoint_parameters) | **POST** /fake | Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
 *FakeApi* | [**test_enum_parameters**](docs/FakeApi.md#test_enum_parameters) | **GET** /fake | To test enum parameters
+*FakeApi* | [**test_inline_additional_properties**](docs/FakeApi.md#test_inline_additional_properties) | **POST** /fake/inline-additionalProperties | test inline additionalProperties
 *FakeApi* | [**test_json_form_data**](docs/FakeApi.md#test_json_form_data) | **GET** /fake/jsonFormData | test json serialization of form data
 *FakeClassnameTags123Api* | [**test_classname**](docs/FakeClassnameTags123Api.md#test_classname) | **PATCH** /fake_classname_test | To test class name in snake case
 *PetApi* | [**add_pet**](docs/PetApi.md#add_pet) | **POST** /pet | Add a new pet to the store
--- a/samples/client/petstore/python/docs/FakeApi.md
+++ b/samples/client/petstore/python/docs/FakeApi.md
@@ -11,6 +11,7 @@ Method | HTTP request | Description
 [**test_client_model**](FakeApi.md#test_client_model) | **PATCH** /fake | To test \&quot;client\&quot; model
 [**test_endpoint_parameters**](FakeApi.md#test_endpoint_parameters) | **POST** /fake | Fake endpoint for testing various parameters 假端點 偽のエンドポイント 가짜 엔드 포인트 
 [**test_enum_parameters**](FakeApi.md#test_enum_parameters) | **GET** /fake | To test enum parameters
+[**test_inline_additional_properties**](FakeApi.md#test_inline_additional_properties) | **POST** /fake/inline-additionalProperties | test inline additionalProperties
 [**test_json_form_data**](FakeApi.md#test_json_form_data) | **GET** /fake/jsonFormData | test json serialization of form data


@@ -389,6 +390,53 @@ No authorization required

 [[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)

+# **test_inline_additional_properties**
+> test_inline_additional_properties(param)
+
+test inline additionalProperties
+
+
+
+### Example 
+```python
+from __future__ import print_function
+import time
+import petstore_api
+from petstore_api.rest import ApiException
+from pprint import pprint
+
+# create an instance of the API class
+api_instance = petstore_api.FakeApi()
+param = NULL # object | request body
+
+try: 
+    # test inline additionalProperties
+    api_instance.test_inline_additional_properties(param)
+except ApiException as e:
+    print("Exception when calling FakeApi->test_inline_additional_properties: %s\n" % e)
+```
+
+### Parameters
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **param** | **object**| request body | 
+
+### Return type
+
+void (empty response body)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: application/json
+ - **Accept**: Not defined
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
 # **test_json_form_data**
 > test_json_form_data(param, param2)

--- a/samples/client/petstore/python/petstore_api/api_client.py
+++ b/samples/client/petstore/python/petstore_api/api_client.py
@@ -42,9 +42,12 @@ class ApiClient(object):
    Ref: https://github.com/swagger-api/swagger-codegen
    Do not edit the class manually.

-    :param host: The base path for the server to call.
+    :param configuration: .Configuration object for this client
    :param header_name: a header to pass when making calls to the API.
-    :param header_value: a header value to pass when making calls to the API.
+    :param header_value: a header value to pass when making calls to 
+        the API.
+    :param cookie: a cookie to include in the header when making calls 
+        to the API
    """

    PRIMITIVE_TYPES = (float, bool, bytes, text_type) + integer_types
@@ -79,16 +82,11 @@ class ApiClient(object):

    @property
    def user_agent(self):
-        """
-        Gets user agent.
-        """
+        """User agent for this API client"""
        return self.default_headers['User-Agent']

    @user_agent.setter
    def user_agent(self, value):
-        """
-        Sets user agent.
-        """
        self.default_headers['User-Agent'] = value

    def set_default_header(self, header_name, header_value):
--- a/samples/client/petstore/python/petstore_api/apis/fake_api.py
+++ b/samples/client/petstore/python/petstore_api/apis/fake_api.py
@@ -784,6 +784,100 @@ class FakeApi(object):
                                        _request_timeout=params.get('_request_timeout'),
                                        collection_formats=collection_formats)

+    def test_inline_additional_properties(self, param, **kwargs):
+        """
+        test inline additionalProperties
+        
+        This method makes a synchronous HTTP request by default. To make an
+        asynchronous HTTP request, please pass async=True
+        >>> thread = api.test_inline_additional_properties(param, async=True)
+        >>> result = thread.get()
+
+        :param async bool
+        :param object param: request body (required)
+        :return: None
+                 If the method is called asynchronously,
+                 returns the request thread.
+        """
+        kwargs['_return_http_data_only'] = True
+        if kwargs.get('async'):
+            return self.test_inline_additional_properties_with_http_info(param, **kwargs)
+        else:
+            (data) = self.test_inline_additional_properties_with_http_info(param, **kwargs)
+            return data
+
+    def test_inline_additional_properties_with_http_info(self, param, **kwargs):
+        """
+        test inline additionalProperties
+        
+        This method makes a synchronous HTTP request by default. To make an
+        asynchronous HTTP request, please pass async=True
+        >>> thread = api.test_inline_additional_properties_with_http_info(param, async=True)
+        >>> result = thread.get()
+
+        :param async bool
+        :param object param: request body (required)
+        :return: None
+                 If the method is called asynchronously,
+                 returns the request thread.
+        """
+
+        all_params = ['param']
+        all_params.append('async')
+        all_params.append('_return_http_data_only')
+        all_params.append('_preload_content')
+        all_params.append('_request_timeout')
+
+        params = locals()
+        for key, val in iteritems(params['kwargs']):
+            if key not in all_params:
+                raise TypeError(
+                    "Got an unexpected keyword argument '%s'"
+                    " to method test_inline_additional_properties" % key
+                )
+            params[key] = val
+        del params['kwargs']
+        # verify the required parameter 'param' is set
+        if ('param' not in params) or (params['param'] is None):
+            raise ValueError("Missing the required parameter `param` when calling `test_inline_additional_properties`")
+
+
+        collection_formats = {}
+
+        path_params = {}
+
+        query_params = []
+
+        header_params = {}
+
+        form_params = []
+        local_var_files = {}
+
+        body_params = None
+        if 'param' in params:
+            body_params = params['param']
+        # HTTP header `Content-Type`
+        header_params['Content-Type'] = self.api_client.\
+            select_header_content_type(['application/json'])
+
+        # Authentication setting
+        auth_settings = []
+
+        return self.api_client.call_api('/fake/inline-additionalProperties', 'POST',
+                                        path_params,
+                                        query_params,
+                                        header_params,
+                                        body=body_params,
+                                        post_params=form_params,
+                                        files=local_var_files,
+                                        response_type=None,
+                                        auth_settings=auth_settings,
+                                        async=params.get('async'),
+                                        _return_http_data_only=params.get('_return_http_data_only'),
+                                        _preload_content=params.get('_preload_content', True),
+                                        _request_timeout=params.get('_request_timeout'),
+                                        collection_formats=collection_formats)
+
    def test_json_form_data(self, param, param2, **kwargs):
        """
        test json serialization of form data
--- a/samples/client/petstore/python/petstore_api/configuration.py
+++ b/samples/client/petstore/python/petstore_api/configuration.py
@@ -109,15 +109,19 @@ class Configuration(with_metaclass(TypeWithDefault, object)):

    @property
    def logger_file(self):
-        """
-        Gets the logger_file.
+        """The logger file.
+
+        If the logger_file is None, then add stream handler and remove file handler.
+        Otherwise, add file handler and remove stream handler.
+
+        :param value: The logger_file path.
+        :type: str
        """
        return self.__logger_file

    @logger_file.setter
    def logger_file(self, value):
-        """
-        Sets the logger_file.
+        """The logger file.

        If the logger_file is None, then add stream handler and remove file handler.
        Otherwise, add file handler and remove stream handler.
@@ -147,15 +151,16 @@ class Configuration(with_metaclass(TypeWithDefault, object)):

    @property
    def debug(self):
-        """
-        Gets the debug status.
+        """Debug status
+
+        :param value: The debug status, True or False.
+        :type: bool
        """
        return self.__debug

    @debug.setter
    def debug(self, value):
-        """
-        Sets the debug status.
+        """Debug status

        :param value: The debug status, True or False.
        :type: bool
@@ -177,15 +182,18 @@ class Configuration(with_metaclass(TypeWithDefault, object)):

    @property
    def logger_format(self):
-        """
-        Gets the logger_format.
+        """The logger format.
+
+        The logger_formatter will be updated when sets logger_format.
+
+        :param value: The format string.
+        :type: str
        """
        return self.__logger_format

    @logger_format.setter
    def logger_format(self, value):
-        """
-        Sets the logger_format.
+        """The logger format.

        The logger_formatter will be updated when sets logger_format.

@@ -196,8 +204,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
        self.logger_formatter = logging.Formatter(self.__logger_format)

    def get_api_key_with_prefix(self, identifier):
-        """
-        Gets API key (with prefix if set).
+        """Gets API key (with prefix if set).

        :param identifier: The identifier of apiKey.
        :return: The token for api key authentication.
@@ -208,8 +215,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
            return self.api_key[identifier]

    def get_basic_auth_token(self):
-        """
-        Gets HTTP basic authentication header (string).
+        """Gets HTTP basic authentication header (string).

        :return: The token for basic HTTP authentication.
        """
@@ -217,8 +223,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
                           .get('authorization')

    def auth_settings(self):
-        """
-        Gets Auth Settings dict for api client.
+        """Gets Auth Settings dict for api client.

        :return: The Auth Settings information dict.
        """
@@ -256,8 +261,7 @@ class Configuration(with_metaclass(TypeWithDefault, object)):
        }

    def to_debug_report(self):
-        """
-        Gets the essential information for debugging.
+        """Gets the essential information for debugging.

        :return: The report for debugging.
        """