doc: Add a script for generating GraphQL API documentation(nervosnetw…

…ork#33)

* doc: auto gen api

* doc: make the field description more clear

Makefile

@@ -21,6 +21,10 @@ doc:
 doc-deps:
 	cargo doc --all
 
+# generate GraphQL API documentation
+doc-api:
+	bash docs/build/gql_api.sh
+
 check:
 	${CARGO} check ${VERBOSE} --all
 
@@ -66,5 +70,5 @@ security-audit:
 	@cargo audit
 
 .PHONY: build prod prod-test
-.PHONY: fmt test clippy doc doc-deps check stats
+.PHONY: fmt test clippy doc doc-deps doc-api check stats
 .PHONY: ci info security-audit

core/api/src/lib.rs

@@ -51,7 +51,7 @@ struct Query;
 // Switch to async/await fn https://github.com/graphql-rust/juniper/issues/2
 #[juniper::object(Context = State)]
 impl Query {
-    #[graphql(name = "getLatestEpoch", description = "get epoch")]
+    #[graphql(name = "getLatestEpoch", description = "Get the latest epoch")]
     fn get_latest_epoch(state_ctx: &State, epoch_id: Option<Uint64>) -> FieldResult<Epoch> {
         let epoch_id = opt_hex_to_u64(epoch_id.map(|id| id.as_hex()))?;
 
@@ -60,7 +60,13 @@ impl Query {
         Ok(Epoch::from(epoch))
     }
 
-    #[graphql(name = "getBalance", description = "get balance")]
+    #[graphql(
+        name = "getBalance",
+        description = "Get the asset balance of an account",
+        arguments(id(description = "The asset id. Asset is the first-class in Muta, \
+            this means that your assets can be more than one in Muta, \
+            and the UDT(User Defined Token) will be supported in the future"))
+    )]
     fn get_balance(
         state_ctx: &State,
         address: Address,
@@ -110,7 +116,7 @@ impl Mutation {
 
     #[graphql(
         name = "sendDeployTransaction",
-        description = "Send deployment contract transactions to the blockchain."
+        description = "Send deployment contract transaction to the blockchain."
     )]
     fn send_deploy_transaction(
         state_ctx: &State,
@@ -132,7 +138,7 @@ impl Mutation {
 
     #[graphql(
         name = "sendUnsafeTransferTransaction",
-        deprecated = "Don't use it! This is just for development testing."
+        deprecated = "DON'T use it in production! This is just for development."
     )]
     fn send_unsafe_transfer_transaction(
         state_ctx: &State,
@@ -159,7 +165,7 @@ impl Mutation {
 
     #[graphql(
         name = "sendUnsafeDeployTransaction",
-        deprecated = "Don't use it! This is just for development testing."
+        deprecated = "DON'T use it in production! This is just for development."
     )]
     fn send_unsafe_deploy_transaction(
         state_ctx: &State,

core/api/src/schema/epoch.rs

@@ -1,26 +1,46 @@
 use crate::schema::{Address, Hash, MerkleRoot, Uint64};
 
 #[derive(GraphQLObject, Clone)]
-#[graphql(description = "Epoch")]
+#[graphql(
+    description = "Epoch is a single digital record created within a blockchain. \
+                   Each epoch contains a record of the previous Epoch, \
+                   and when linked together these become the “chain”.\
+                   An epoch is always composed of header and body."
+)]
 pub struct Epoch {
-    header:            EpochHeader,
+    #[graphql(description = "The header section of an epoch")]
+    header: EpochHeader,
+    #[graphql(description = "The body section of an epoch")]
     ordered_tx_hashes: Vec<Hash>,
 }
 
 #[derive(GraphQLObject, Clone)]
-#[graphql(description = "Epoch header")]
+#[graphql(description = "An epoch header is like the metadata of an epoch.")]
 pub struct EpochHeader {
-    pub chain_id:     Hash,
-    pub epoch_id:     Uint64,
-    pub pre_hash:     Hash,
-    pub timestamp:    Uint64,
-    pub order_root:   MerkleRoot,
+    #[graphql(
+        description = "Identifier of a chain in order to prevent replay attacks across channels "
+    )]
+    pub chain_id: Hash,
+    #[graphql(description = "Known as the block height like other blockchain")]
+    pub epoch_id: Uint64,
+    #[graphql(description = "The hash of the serialized previous epoch")]
+    pub pre_hash: Hash,
+    #[graphql(description = "A timestamp that records when the epoch was created")]
+    pub timestamp: Uint64,
+    #[graphql(description = "The merkle root of ordered transactions")]
+    pub order_root: MerkleRoot,
+    #[graphql(description = "The merkle roots of all the confirms")]
     pub confirm_root: Vec<MerkleRoot>,
-    pub state_root:   MerkleRoot,
+    #[graphql(description = "The merkle root of state root")]
+    pub state_root: MerkleRoot,
+    #[graphql(description = "The merkle roots of receipts")]
     pub receipt_root: Vec<MerkleRoot>,
-    pub cycles_used:  Uint64,
-    pub proposer:     Address,
+    #[graphql(description = "The sum of all transactions costs")]
+    pub cycles_used: Uint64,
+    #[graphql(description = "The address descirbed who packed the epoch")]
+    pub proposer: Address,
     // proof:             Proof,
+    #[graphql(description = "The version of validator is designed for cross chain")]
     pub validator_version: Uint64,
     // validators:        Vec<Validator>,
 }

core/api/src/schema/mod.rs

@@ -8,7 +8,7 @@ pub use transaction::{
 };
 
 #[derive(GraphQLScalarValue, Clone)]
-#[graphql(description = "Keccak hash of hex string")]
+#[graphql(description = "The output digest of Keccak hash function")]
 pub struct Hash(String);
 pub type MerkleRoot = Hash;
 pub type AssetID = Hash;

core/api/src/schema/transaction.rs

@@ -1,12 +1,20 @@
 use crate::schema::{Address, AssetID, Balance, Bytes, Hash, Uint64};
 
 #[derive(GraphQLEnum, Clone)]
+#[graphql(description = "According to different purposes, Muta has many contract type")]
 pub enum ContractType {
     // Asset contract
+    #[graphql(
+        description = "Asset contract often use for creating User Define Asset(also known as UDT(User Define Token))"
+    )]
     Asset,
     // App contract, the code in the contract is allowed to change the state world.
+    #[graphql(
+        description = "App contract often use for creating DAPP(Decentralized APPlication) "
+    )]
     App,
     // Library contract, the code in the contract is not allowed to change the state world.
+    #[graphql(description = "Library contract often providing reusable and immutable function")]
     Library,
 }
 
@@ -15,34 +23,59 @@ pub enum ContractType {
 // #####################
 
 #[derive(GraphQLInputObject, Clone)]
-#[graphql(description = "input raw transaction.")]
+#[graphql(description = "There was many types of transaction in Muta, \
+                         A transaction often require computing resources or write data to chain,\
+                         these resources are valuable so we need to pay some token for them.\
+                         InputRawTransaction describes information above")]
 pub struct InputRawTransaction {
-    pub chain_id:     Hash,
-    pub fee_cycle:    Uint64,
+    #[graphql(description = "Identifier of the chain.")]
+    pub chain_id: Hash,
+    #[graphql(
+        description = "Mostly like the gas limit in Ethereum, describes the fee that \
+                       you are willing to pay the highest price for the transaction"
+    )]
+    pub fee_cycle: Uint64,
+    #[graphql(description = "asset type")]
     pub fee_asset_id: AssetID,
-    pub nonce:        Hash,
-    pub timeout:      Uint64,
+    #[graphql(
+        description = "Every transaction has its own id, unlike Ethereum's nonce,\
+                       the nonce in Muta is an hash"
+    )]
+    pub nonce: Hash,
+    #[graphql(description = "For security and performance reasons, \
+    Muta will only deal with trade request over a period of time,\
+    the `timeout` should be `timeout > current_epoch_height` and `timeout < current_epoch_height + timeout_gap`,\
+    the `timeout_gap` generally equal to 20.")]
+    pub timeout: Uint64,
 }
 
 #[derive(GraphQLInputObject, Clone)]
-#[graphql(description = "input signature, hash, pubkey")]
+#[graphql(description = "Signature of the transaction")]
 pub struct InputTransactionEncryption {
-    pub tx_hash:   Hash,
-    pub pubkey:    Bytes,
+    #[graphql(description = "The digest of the transaction")]
+    pub tx_hash: Hash,
+    #[graphql(description = "The public key of transfer")]
+    pub pubkey: Bytes,
+    #[graphql(description = "The signature of the transaction")]
     pub signature: Bytes,
 }
 
 #[derive(GraphQLInputObject, Clone)]
-#[graphql(description = "input transfer action.")]
+#[graphql(description = "The action of transfer transaction")]
 pub struct InputTransferAction {
-    pub carrying_amount:   Balance,
+    #[graphql(description = "The amount of the transfer")]
+    pub carrying_amount: Balance,
+    #[graphql(description = "The asset of of the transfer")]
     pub carrying_asset_id: AssetID,
-    pub receiver:          Address,
+    #[graphql(description = "The receiver of the transfer")]
+    pub receiver: Address,
 }
 
 #[derive(GraphQLInputObject, Clone)]
-#[graphql(description = "input deploy action.")]
+#[graphql(description = "The deploy transfer transaction")]
 pub struct InputDeployAction {
-    pub code:          Bytes,
+    #[graphql(description = "Encoded contract code")]
+    pub code: Bytes,
+    #[graphql(description = "The type of contract")]
     pub contract_type: ContractType,
 }

docs/build/gql_api.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+BASEDIR=$(dirname "$0")
+
+function check() {
+  if ! type "$1" > /dev/null; then
+  echo "$1 is required, install first $2"
+  echo $2
+  exit 1
+fi
+}
+
+check node
+check graphql-markdown "run npm install graphql-markdown --global"
+
+endpoint="http://127.0.0.1:8000/graphql"
+if [ ! -z "$1" ]; then
+  endpoint=$1
+fi
+
+res_code=$(curl --write-out %{http_code} --silent --output /dev/null \
+            -X POST -d '{"query":"query { getLatestEpoch { header { epochId }}}"}' \
+            $endpoint)
+
+if [ $res_code -ne 200 ]; then
+  echo "$endpoint GraphQL endpoint request failed"
+  echo "start API server at first or use the custom endpoint make doc-api http://x.x.x.x:8000/graphql"
+  exit 1;
+fi
+
+prologue="
+>[GraphQL](https://graphql.org) is a query language for APIs and a runtime for fulfilling those queries with your existing data.
+GraphQL provides a complete and understandable description of the data in your API,
+gives clients the power to ask for exactly what they need and nothing more,
+makes it easier to evolve APIs over time, and enables powerful developer tools.
+
+Muta has embeded a [Graph*i*QL](https://github.com/graphql/graphiql) for checking and calling API. Started a the Muta
+node, and then try open http://127.0.0.1:8000/graphiql in the browser.
+"
+
+graphql-markdown $endpoint --title "Muta GraphQL API" --prologue "$prologue" > $BASEDIR/../graphql_api.md