walder
v4.1.3
A Walder oferece uma maneira fácil de configurar uma API de site ou web sobre os gráficos de conhecimento descentralizados. Os gráficos de conhecimento incorporam dados juntamente com o significado desses dados. Isso torna possível combinar dados de vários gráficos de conhecimento, mesmo que partes diferentes e independentes os mantenham ou hospedem. Os gráficos de conhecimento podem ser hospedados por meio de vagens sólidas, terminais SPARQL, interfaces de fragmentos de padrões triplos, arquivos RDF e assim por diante. Usando a negociação de conteúdo, Walder disponibiliza os dados nesses gráficos de conhecimento para clientes via HTML, RDF e JSON-LD. Os usuários definem em um arquivo de configuração que dados usa e como processa esses dados. Descubra quais APIs são construídas com Walder aqui.
Índice
Instale o Walder globalmente via yarn global add walder .
Para o desenvolvimento, siga estas etapas:
yarn install .$ yarn global add file:$(pwd) . Walder está disponível como uma biblioteca CLI e JavaScript.
Usage: walder [options]
Options:
-v, --version output the version number
-c, --config < configFile > YAML configuration file input
-p, --port [portNumber] server port number (default: 3000)
-l, --log [level] enable logging and set logging level (one of [error, warn, info, verbose, debug]) (default: " info " )
--no-cache disable Comunica default caching
--lenient turn Comunica errors on invalid data into warnings
-h, --help output usage information // From the root directory
const Walder = require ( '.' ) ;
const configFilePath = 'path/to/configfile' ;
const port = 9000 ; // Defaults to 3000
const logging = 'info' ; // Defaults to 'info'
const cache = false ; // Defaults to true
const lenient = true ; // Defaults to false
const walder = new Walder ( configFilePath , { port , logging , cache , lenient , cwd } ) ;
walder . activate ( ) ; // Starts the server
walder . deactivate ( ) ; // Stops the serverVocê escreve um arquivo de configuração na YAML após a especificação OpenAPI 3.0. O arquivo de configuração deve ter a seguinte estrutura:
openapi : 3.0.2
info : # OpenAPI metadata
title : ' Example site '
version : 0.1.0
x-walder-resources : # Directories used by Walder - OPTIONAL
root : # Path to the root folder of the directories used by Walder (absolute or relative to the directory containing the config file) - OPTIONAL (default: .)
views : # Path to directory containing view template files (absolute or relative to the root folder) - OPTIONAL (default: views)
pipe-modules : # Path to directory containing local pipe modules (absolute or relative to the root folder) - OPTIONAL (default: pipe-modules)
public : # Path to directory containing all files that should be available statically (e.g. stylesheets) (absolute or relative to the root folder) - OPTIONAL (default: public)
layouts : # Path to directory containing all layout template files that can be used by view template files (absolute or relative to the root folder) - OPTIONAL (default: layouts)
x-walder-datasources : # Default list of data sources
- ... # E.g. link to SPARQL endpoint or a GraphQL-LD query
paths : # List of path entries
path-entry-1 :
...
path-entry-2 :
...
x-walder-errors : # Default error page views - status codes with files containing the HTML view template (absolute path or relative to the views directory)
404 : ...
500 : ...
... A tecla x-walder-resources do arquivo de configuração contém caminhos para os diretórios usados pelo Walder. Esta chave e seus valores são opcionais. Se um usuário não fornece caminhos, o Walder usará os seguintes valores padrão em relação ao diretório do arquivo de configuração.
root : .
views : views
pipe-modules : pipe-modules
public : public
layouts : layouts Para impedir que Walder torne o arquivo errado, quando um usuário não dá um caminho para o campo public , o Walder cria um novo diretório public se não encontrar esse diretório no diretório de trabalho atual e usar um.
Uma entrada de caminho define uma rota e tem a seguinte estrutura:
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
json-ld-context : ... # The JSON-LD corresponding to the GraphQL query
sparql-query : ... # One or more SPARQL queries
json-ld-frame : ... # A JSON-LD frame that should be applied to the result of a SPARQL query
options : # Global options that will be applied to all the graphql-queries of this path (OPTIONAL)
datasources : # Query specific datasources (OPTIONAL)
additional : ... # Boolean stating that the following datasources are meant to be used on top of the default ones
sources : # List of query specific datasources
- ... # E.g. link to SPARQL endpoint
x-walder-postprocessing : # The (list of) pipe modules used for postprocessing
module-id : # Identifier of the pipe module
source : ... # Path leading to source code of the pipe module (absolute path or relative to the pipe-modules directory)
parameters : # the parameters for the pipe module (OPTIONAL)
- _data # (DEFAULT) this gives all the data, but all paths in the data object are supported (e.g. _data.0.employee)
- ... # Additional parameters if your function supports those (OPTIONAL)
responses : # Status codes with files containing the HTML view template (absolute path or relative to the views directory)
200 : ... # (REQUIRED)
500 : ... # (OPTIONAL)O comando a seguir inicia um servidor na porta 3000 (padrão) usando um arquivo de configuração de exemplo.
$ walder -c example/config.yaml
Isso iniciará um servidor no localhost:3000 com as seguintes rotas:
Na entrada do caminho acima, o usuário definiu options como um identificador global (opcional) que o Walder usa para todas as consultas desse caminho. Temos duas opções nas quais podemos escolher: sort e remove-duplicates . Com dada sintaxe:
options :
sort : # Enable sorting on the data (OPTIONAL)
object : # JSONPath to the object you want to sort for
selectors : # The values inside the object over which you want to sort
- ... # The default option when you want ascending order, just give the value (JSONPath notation supported for further nesting)
- value : ... # When you want descending order, specify the value/order (JSONPath notation supported for further nesting)
order : desc
remove-duplicates : # Enable the removal of duplicates of the data (OPTIONAL)
object : ... # The JSONPath tot the object that you want to compare
value : ... # The value that has to be compared to determine whether it's duplicate (JSONPath notation is also supported for further nesting) Se você não deseja que options sejam globais para todo o caminho, pode definir options por consulta.
path : # The path linked to this query
request : # The HTTP request type (GET, POST, etc.)
summary : ... # Short description
parameters : # Path variables/Query parameters
- in : ... # 'path' or 'query'
name : ... # Name of the parameter
schema :
type : ... # Type of the parameter
description : ... # Description of the parameter
x-walder-query :
graphql-query : ... # One or more GraphQL queries
name :
query : ... # The GraphQL query
options : # options that will be applied only to this specific graphql-query (OPTIONAL)
...O comando a seguir inicia um servidor usando este arquivo de configuração.
$ walder -c example/config-sorting-duplicates.yaml
Isso iniciará um servidor no localhost:3000 com as seguintes rotas:
Você pode dividir um arquivo de configuração em vários arquivos, usando a palavra -chave $ref . Seguimos a especificação OpenAPI 3.0 que explica como usar a referência.
Quando referenciado pela primeira vez, você precisa usar o caminho que inicia no diretório do arquivo de configuração, mas se o arquivo referenciado tiver referências, ele poderá usar os caminhos em relação ao seu próprio local, como mostrado abaixo.
O arquivo de configuração real referenciando seus caminhos
openapi : 3.0.2
info :
title : ' Example site '
version : 0.1.0
x-walder-resources :
path : ./
views : views
pipe-modules : pipeModules
public : public
x-walder-datasources :
- http://fragments.dbpedia.org/2016-04/en
paths :
/music/{musician} :
$ref : ' ./paths/music_musician.yaml '
/movies/{actor} :
$ref : ' ./paths/movies_actor.yaml '
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html Abaixo você vê ./example/paths/movies_actor.yaml com referência com caminho em relação à sua própria localização
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : path
name : actor
required : true
schema :
type : string
description : The target actor
x-walder-query :
$ref : ' ../walderQueryInfo/movies_actor_info.yaml '
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
Usando a negociação de conteúdo, Walder disponibiliza os seguintes formatos de saída:
Walder usa grafql-ld-comunica para executar as consultas grafql e @comunica/query-sparql para executar consultas SPARQL. O resultado de uma consulta grafQL-LD é um dados JSON. Walder primeiro converte-o em JSON-LD. Isso permite a conversão para outros formatos de RDF durante a negociação de conteúdo. O resultado de uma consulta SPARQL é uma variedade de quadríceps. Se um quadro JSON-LD for especificado, os quads serão convertidos em JSON-LD. Devido à importância da negociação de conteúdo, apenas consultas de construção são suportadas.
Walder usa o consolidado para recuperar automaticamente o mecanismo correspondente para um determinado modelo. Isso significa que os mecanismos de modelo suportados dependem do consolidar.
Você pode usar diferentes motores de modelo para diferentes rotas, por exemplo, o PUG renderiza o HTML de uma rota, enquanto o guidão renderiza o HTML de outra rota. Walder faz tudo isso olhando para a extensão do arquivo do modelo fornecido.
Os modelos podem ser usados nas vistas e nos layouts. Então, o nomearemos de visualizar modelos e modelos de layout para distinguir.
Os resultados das consultas, especificados no arquivo de configuração de uma rota, estão disponíveis para renderizar os modelos de exibição como dados.
data . No caso de uma consulta grafql-LD, cada objeto será uma matriz, a menos que a consulta tenha sido singularizada. Songs.HandleBars é um exemplo do consumo do resultado da consulta única na rota /music/{musician} neste arquivo de configuração. Songs_movies.HandleBars é um exemplo do consumo dos resultados das duas consultas na rota /artist/{artist} neste arquivo de configuração.
No caso de uma consulta SPARQL, cada objeto é uma matriz de quads se nenhum quadro JSON-LD for especificado. Caso contrário, será um objeto JSON-LD.
Usar layouts é uma ótima maneira de evitar a repetição em modelos de visão específicos da rota. Estruturas HTML reutilizáveis, como cabeçalhos, rodapés, barras de navegação e outros conteúdos, destinados a aparecer em várias rotas, são preferíveis especificados nos arquivos de layout .
Um arquivo de modelo de layout pode ser especificado em um arquivo de modelo de exibição, por meio do layout do campo de metadados da frente. Ele deve conter um nome de arquivo, disponível no local layouts definido no arquivo de configuração. Pode conter um caminho relativo na frente do nome do arquivo.
Exemplo de exibir arquivo de modelo especificando um layout:
---
layout: my-layout.pug
---
// view template continues here
Walder coloca o conteúdo HTML interno gerado a partir do arquivo de modelo de exibição nos dados encaminhados ao arquivo de modelo de layout como um objeto chamado content .
O arquivo de modelo de layout é mais um modelo. Geralmente expande esses conteúdos HTML internos na posição de sua escolha.
Um exemplo simples de pug (lembre -se do !{content} ):
doctype html
html(lang="en")
head
title I'm based on a layout
body !{content}
Além dos resultados da consulta, Walder adiciona metadados frontal, especificados nos modelos de exibição, como atributos adicionais aos dados.
O nome de cada atributo adicional é igual ao nome do campo de metadados fornecido. O campo de metadados a seguir é reservado: layout , content , data e nomes atribuídos a consultas em rotas com várias consultas (veja acima).
Esses atributos estão disponíveis para o modelo de exibição e para o modelo de layout que ele se refere, se houver.
Exemplo de visualização do arquivo de modelo especificando um campo de metadados da frente e lendo esse campo (lembre-se do #{a1} ):
--
a1: Value for FrontMatter attribute a1!
---
doctype html
html(lang="en")
body
main a1: #{a1}
Exemplo de exibir arquivo de modelo, especificando um modelo de layout e outro campo de metadados da frente:
---
layout: layout-fm.pug
a2: Value for FrontMatter attribute a2!
---
main Lorem ipsum
Exemplo de modelo de layout correspondente (layout-fm.pug) lendo esse campo (lembre-se do #{a2} ):
doctype html
html(lang="en")
head
if a2
title #{a2}
body !{content}
Ao analisar o arquivo de configuração, Walder também valida a correção e a integridade da entrada. Quando o Walder analisou todo o arquivo de configuração e encontrou erros, o Walder retorna todos os erros e saídas.
No momento, Walder valida o seguinte:
200~x-walder-input-text/html . Walder liga as páginas de erro a um determinado código de status HTTP. Você pode definir páginas de erro padrão, mas também as páginas de erro específicas do caminho, adicionando -as à chave responses na entrada do caminho correspondente.
404 : página não encontrada500 : erro interno do servidor 500 : não foi possível aplicar os módulos de tubo especificados 404 : a variável esperada não foi dada500 : não foi possível executar a consulta fornecidaQuando você executa Walder usando o seguinte comando:
$ walder -c example/config-errors.yaml
Os seguintes caminhos levam a erros:
404 (global: página não encontrada)500 (módulos do tubo: não foi possível aplicar os módulos de tubo fornecidos)500 (grafql-ld: não pôde executar a consulta fornecida) O trecho de arquivo de configuração a seguir usará o caminho de moviesServerError.handlebars PATH MODELO DE ERROS que levam ao código de status 500 ao navegar em /movies .
Quando o actor de parâmetro de consulta necessário não é aprovado, Walder retorna o código de status 404 . O Walder usará o arquivo error404.html padrão, pois o arquivo de configuração não possui um modelo de exibição HTML específico do caminho para o status correspondente.
...
paths :
/movies :
get :
summary : Returns a list of the all movies the given actor stars in
parameters :
- in : query
name : actor
schema :
type : string
minimum : 0
description : The actor from whom the movies are requested
required : true
x-walder-query :
graphql-query : >
{
id @single
... on Film {
starring(label: $actor) @single
}
}
json-ld-context : >
{
"@context": {
"Film": "http://dbpedia.org/ontology/Film",
"label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
"starring": "http://dbpedia.org/ontology/starring"
}
}
responses :
200 :
description : list of movies
x-walder-input-text/html : movies.pug
500 :
description : internal movie server error
x-walder-input-text/html : moviesServerError.handlebars
x-walder-errors :
404 :
description : page not found error
x-walder-input-text/html : error404.html
500 :
description : internal server error
x-walder-input-text/html : error500.html Enquanto desenvolve seu site, você provavelmente deseja que seu site recarregue enquanto faz alterações no config.yaml . Você pode fazer isso facilmente usando o NPM-Watch. Veja o snippet package.json abaixo sobre como começar
{
"watch" : {
"run" : " config.yaml "
},
"scripts" : {
"run" : " walder -c config.yaml --no-cache " ,
"watch" : " npm-watch "
},
"dependencies" : {
"walder" : " ^2.0.1 "
},
"devDependencies" : {
"npm-watch" : " ^0.7.0 "
}
} Execute npm run watch e Walder Recaroades todas as mudanças config.yaml !
| Biblioteca | Licença |
|---|---|
| @comunica | Mit |
| aceita | Mit |
| Axios | Mit |
| Chai | Mit |
| comandante | Mit |
| consolidar | Mit |
| depurar | Mit |
| expressar | Mit |
| Front-Matter | Mit |
| fs-extra | Mit |
| GraphQL-LD | Mit |
| GraphQL-LD-Comunica | Mit |
| guidão | Mit |
| is-html | Mit |
| Jade-a-Handlebars | Mit |
| JSON-REFS | Mit |
| jsonld | BSD-3-cláusula |
| jsonpath | Mit |
| Markdown-it | Mit |
| Mocha | Mit |
| Morgan | Mit |
| n3 | Mit |
| caminho de objeto | Mit |
| pug | Mit |
| Supertest | Mit |
| TMP | Mit |
| Winston | Mit |
| Yaml | ISC |
Você construiu algo Walder e queria adicioná -lo à lista? Por favor, crie um pedido de tração!
Este código é protegido por direitos autorais © 2019–2020 pela Universidade Ghent - IMEC e liberado sob a licença do MIT.
