BC-72 Add and configure drf-spectacular module.

Author: olegtropinin

.gitignore

@@ -53,6 +53,7 @@ nosetests.xml
 
 # pytest
 .pytest_cache
+node/blockchain/tests/examples/testing.json
 
 # mypy
 .mypy_cache

.pre-commit-config.yaml

@@ -42,4 +42,4 @@ repos:
     rev: 'v0.910'
     hooks:
       - id: mypy
-        additional_dependencies: [types-requests, types-PyYAML]
+        additional_dependencies: [types-requests, types-PyYAML, types-toml]

node/blockchain/admin.py

@@ -12,4 +12,4 @@ class BlockAdmin(admin.ModelAdmin):
 
 @admin.register(AccountState)
 class AccountStateAdmin(admin.ModelAdmin):
-    pass
+    list_display = ('_id',)

node/blockchain/constants.py

@@ -5,3 +5,16 @@
 
 LAST_BLOCK_ID = 'last'
 BLOCK_LOCK = 'block'
+
+NODE_DETAILS_EXAMPLE = 'node_details'
+NODE_LIST_EXAMPLE = 'node_list'
+ACCOUNT_STATE_DETAILS_EXAMPLE = 'account_state_details'
+
+BLOCK_DETAILS_GENESIS_EXAMPLE = 'block_details_genesis'
+BLOCK_DETAILS_COIN_TRANSFER_EXAMPLE = 'block_details_coin_transfer'
+BLOCK_DETAILS_NODE_DECLARATION_EXAMPLE = 'block_details_node_declaration'
+BLOCK_DETAILS_PV_SCHEDULE_UPDATE_EXAMPLE = 'block_details_pv_schedule_update'
+BLOCK_LIST_EXAMPLE = 'block_list'
+
+SIGNED_CHANGE_REQUEST_COIN_TRANSFER_EXAMPLE = 'signed_change_request_coin_transfer'
+SIGNED_CHANGE_REQUEST_NODE_DECLARATION_EXAMPLE = 'signed_change_request_node_declaration'

node/blockchain/serializers/account_state.py

@@ -6,6 +6,11 @@
 
 
 class AccountStateSerializer(serializers.ModelSerializer):
+    """
+    Account state, which defines a set of attributes about the current account state, such as account balance
+    (the amount of coins owned by an account). These attributes change over time.
+    """
+
     _id = serializers.CharField()
     balance = serializers.IntegerField()
     account_lock = serializers.CharField()

node/blockchain/serializers/block.py

@@ -11,6 +11,14 @@
 
 
 class BlockSerializer(serializers.ModelSerializer):
+    """
+    Block are structure that store data. These data describe changes to the network and originate
+    from signed change requests, such as:<br>
+    * Genesis;<br>
+    * Transfers of coins between accounts;<br>
+    * New nodes being added to the network;<br>
+    * Primary Validator Schedule Updates.
+    """
 
     signer = serializers.CharField(min_length=64, max_length=64, write_only=True)
     signature = serializers.CharField(min_length=128, max_length=128, write_only=True)

node/blockchain/serializers/node.py

@@ -4,6 +4,12 @@
 
 
 class NodeSerializer(serializers.ModelSerializer):
+    """
+    The network uses multiple nodes, which are servers with several responsibilities.
+    Nodes connect users or client apps to the network, or enable important processes,
+    such as transaction validation.
+    """
+
     # TODO(dmu) HIGH: Instead of redefining serializer fields generate serializer from
     #                 Node model metadata
     identifier = serializers.CharField()

node/blockchain/serializers/signed_change_request.py

@@ -15,6 +15,12 @@
 
 
 class SignedChangeRequestSerializer(serializers.Serializer, ValidateUnknownFieldsMixin):
+    """
+    Signed change request is a data update request. Next types are allowed:<br>
+    * Transfers of coins between accounts;<br>
+    * New nodes being added to the network.<br>
+    """
+
     signer = serializers.CharField()
     signature = serializers.CharField()
     message = PydanticModelBackedJSONField()

node/blockchain/tests/examples.py

@@ -0,0 +1,50 @@
+import functools
+import json
+import logging
+import os
+from pathlib import Path
+
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+EXAMPLES_DIR = os.path.join(Path(__file__).resolve().parent, 'examples')
+
+
+def save_example(file_name, data):
+    if not settings.IN_DOCKER:
+        with open(get_example_path(file_name), 'w') as fp:
+            json.dump(data, fp)
+
+
+def save_response_as_example(file_name):
+
+    def save(func):
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            data = func(*args, **kwargs)
+            assert data is not None
+
+            save_example(file_name, data)
+
+            return data
+
+        return wrapper
+
+    return save
+
+
+def load_example(file_name):
+    path = get_example_path(file_name)
+
+    if not os.path.exists(path):
+        logger.warning("%s example file doesn't exist: %s", file_name, path)
+        return {}
+
+    with open(path) as fp:
+        return json.load(fp)
+
+
+def get_example_path(file_name):
+    return os.path.join(EXAMPLES_DIR, f'{file_name}.json')

node/blockchain/tests/examples/account_state_details.json

@@ -0,0 +1 @@
+{"_id": "b9dc49411424cce606d27eeaa8d74cb84826d8a1001d17603638b73bdc6077f1", "balance": 0, "account_lock": "b9dc49411424cce606d27eeaa8d74cb84826d8a1001d17603638b73bdc6077f1", "node": {"identifier": "b9dc49411424cce606d27eeaa8d74cb84826d8a1001d17603638b73bdc6077f1", "addresses": ["http://not-existing-primary-validator-address-674898923.com:8555/"], "fee": 4}}