Graphiql的Sphinx扩展
sphinx-graphiql的Python项目详细描述
狮身人面像
这是一个sphinx的graphiql插件，允许您从文档中进行graphql查询。
我们构建这个是为了记录Hasura GraphQL engine的api。在行动中检查它here。（注意：在我们的文档中，我们添加了定制的css覆盖以使graphiql看起来符合我们的需要）
用法
要在.rst文档中插入graphiql组件，请使用声明性：
.. graphiql::
:query:
query {
author {
id
name
}
}
仅查看
如果只想使graphiql视图（即：禁用执行），只需添加另一个选项:view_only:。例如：
.. graphiql::
:view_only:
:query:
query {
author {
id
name
}
}
显示虚拟响应
有时您会希望在不执行查询的情况下显示响应和查询。您可以通过添加:response:选项来实现这一点。
.. graphiql::
:view_only:
:query:
query {
author {
id
name
}
}
:response:
{
"data": {
"author": [
{
"id": 1
"name": "Justin",
},
{
"id": 2
"name": "Beltran",
},
{
"id": 3
"name": "Sidney",
}
]
}
}
自定义端点
默认情况下，graphql端点是从环境变量中提取的，如here所述。
如果要显式设置查询的端点，可以添加:endpoint:选项。
.. graphiql::
:endpoint: http://localhost:8080/v1/graphql
:query:
query {
author {
id
name
}
}
安装
步骤1：安装插件
$ pip install sphinx_graphiql
步骤2：在conf.py
中将插件作为扩展提到
您可能正在文档中使用其他扩展。将sphinx_graphiql附加到扩展列表。
extensions.append('sphinx_graphiql')
步骤3：将所需脚本添加到模板html
在模板html文件的<head></head>中添加以下标记（通常是layout.html）。
<!-- GraphiQL --><scriptsrc="//cdn.jsdelivr.net/react/15.4.2/react.min.js"></script><scriptsrc="//cdn.jsdelivr.net/react/15.4.2/react-dom.min.js"></script><scriptsrc="https://rawgit.com/hasura/sphinx_graphiql/master/static/graphiql/graphiql.min.js"></script><linkhref="https://rawgit.com/hasura/sphinx_graphiql/master/static/graphiql/graphiql.css"rel="stylesheet"><linkhref="https://rawgit.com/hasura/sphinx_graphiql/master/static/styles.css"rel="stylesheet"><scripttype="text/javascript">// graphql query fetcherconstgraphQLFetcher=function(endpoint){endpoint=endpoint||"{{ GRAPHIQL_DEFAULT_ENDPOINT }}";returnfunction(graphQLParams){constparams={method:'post',headers:{'Accept':'application/json','Content-Type':'application/json'},body:JSON.stringify(graphQLParams),credentials:'include'};returnfetch(endpoint,params).then(function(response){returnresponse.text();}).then(function(responseBody){try{returnJSON.parse(responseBody);}catch(error){returnresponseBody;}});}};// create GraphiQL components and embed into HTMLconstsetupGraphiQL=function(){if(typeof(React)==='undefined'||typeof(ReactDOM)==='undefined'||typeof(GraphiQL)==='undefined'){return;}consttargets=document.getElementsByClassName('graphiql');for(leti=0;i<targets.length;i++){consttarget=targets[i];constendpoint=target.getElementsByClassName("endpoint")[0].innerHTML.trim();constquery=target.getElementsByClassName("query")[0].innerHTML.trim();constresponse=target.getElementsByClassName("response")[0].innerHTML.trim();constgraphiQLElement=React.createElement(GraphiQL,{fetcher:graphQLFetcher(endpoint),schema:null,// TODO: Pass undefined to fetch schema via introspectionquery:query,response:response});ReactDOM.render(graphiQLElement,target);}};// if graphiql elements present, setup graphiqlif(document.getElementsByClassName('graphiql').length>0){setupGraphiQL();}</script>
You can find these tags at
static/static.htmlof the root directory.
配置
默认GraphQL端点
必须将graphql端点设置为sphinx配置文件中的环境变量（通常是项目根目录中的conf.py）。
例如：
GRAPHIQL_DEFAULT_ENDPOINT="https://graphql.my-graphql-app.io/v1/graphql"
自动完成
graphiql使用graphql模式在输入查询和突变时自动完成。
如果graphql端点支持内省，只需将undefined作为模式变量传递，然后
自动完成将开箱即用。
constgraphiQLElement=React.createElement(GraphiQL,{fetcher:graphQLFetcher(endpoint),schema:undefined,// the schema will be fetched using introspectionquery:query,response:response});
欢迎加入QQ群-->： 979659372
