swaggerexpert/openapi-server-url-templatingPublic

NotificationsYou must be signed in to change notification settings
Fork1
Star4

OpenAPI Server URL templating parser, validator and substitution mechanism.

License

Apache-2.0 license

4 stars 1 fork Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 152 Commits
.github		.github
.husky		.husky
scripts		scripts
src		src
test		test
types		types
.browserslistrc		.browserslistrc
.commitlintrc.json		.commitlintrc.json
.editorconfig		.editorconfig
.gitignore		.gitignore
.mocharc.json		.mocharc.json
.nvmrc		.nvmrc
.prettierrc		.prettierrc
.releaserc		.releaserc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
babel.config.cjs		babel.config.cjs
package-lock.json		package-lock.json
package.json		package.json

Repository files navigation

openapi-server-url-templating

Server URL Templating supportsServer Variables. Variable substitutions will be made when a variable is named in{brackets}.This mechanism is used byServer ObjectofOpenAPI specification.

openapi-server-url-templating is aparser,validator andsubstitution mechanism for OpenAPI Server URL Templating,which played afoundational role in defining the official ANBF grammar for Server URL Templating.

It supports Server Object URL Templating defined in following OpenAPI specification versions:

Get professionally supported openapi-server-url-templating with Tidelift Subscription.

Getting started

Installation

You can installopenapi-server-url-templating usingnpm:

 $ npm install openapi-server-url-templating

Usage

openapi-server-url-templating currently supportsparsing,validation andsubstitution.Both parser and validator are based on a superset ofABNF (SABNF)and useapg-lite parser generator.

Parsing

Parsing a Server URL Templating is as simple as importing theparse functionand calling it.

import{parse}from'openapi-server-url-templating';constparseResult=parse('https://{username}.gigantic-server.com:{port}/{basePath}');parseResult.result.success;// => true

parseResult variable has the following shape:

{  result: {    success: true,    state: 101,    stateName: 'MATCH',    length: 56,    matched: 56,    maxMatched: 56,    maxTreeDepth: 12,    nodeHits: 758  },  ast: fnast {    callbacks: [      'server-url-template': [Function: serverUrlTemplate],      'server-variable': [Function: serverVariable],      'server-variable-name': [Function: serverVariableName],      literals: [Function: literals]    ],    init: [Function (anonymous)],    ruleDefined: [Function (anonymous)],    udtDefined: [Function (anonymous)],    down: [Function (anonymous)],    up: [Function (anonymous)],    translate: [Function (anonymous)],    setLength: [Function (anonymous)],    getLength: [Function (anonymous)],    toXml: [Function (anonymous)]  }}

Interpreting AST as list of entries

import{parse}from'openapi-server-url-templating';constparseResult=parse('https://{username}.gigantic-server.com:{port}/{basePath}');constparts=[];parseResult.ast.translate(parts);

After running the above code,parts variable has the following shape:

[['server-url-template','https://{username}.gigantic-server.com:{port}/{basePath}'],['literals','https://'],['server-variable','{username}'],['server-variable-name','username'],['literals','.gigantic-server.com:'],['server-variable','{port}'],['server-variable-name','port'],['literals','/'],['server-variable','{basePath}'],['server-variable-name','basePath']]

Interpreting AST as XML

import{parse}from'openapi-server-url-templating';constparseResult=parse('https://{username}.gigantic-server.com:{port}/{basePath}');constxml=parseResult.ast.toXml();

After running the above code,xml variable has the following content:

<?xml version="1.0" encoding="utf-8"?><rootnodes="10"characters="56"><!-- input string-->  https://{username}.gigantic-server.com:{port}/{basePath}  <nodename="server-url-template"index="0"length="56">    https://{username}.gigantic-server.com:{port}/{basePath}    <nodename="literals"index="0"length="8">      https://    </node><!-- name="literals"-->    <nodename="server-variable"index="8"length="10">      {username}      <nodename="server-variable-name"index="9"length="8">        username      </node><!-- name="server-variable-name"-->    </node><!-- name="server-variable"-->    <nodename="literals"index="18"length="21">      .gigantic-server.com:    </node><!-- name="literals"-->    <nodename="server-variable"index="39"length="6">      {port}      <nodename="server-variable-name"index="40"length="4">        port      </node><!-- name="server-variable-name"-->    </node><!-- name="server-variable"-->    <nodename="literals"index="45"length="1">      /    </node><!-- name="literals"-->    <nodename="server-variable"index="46"length="10">      {basePath}      <nodename="server-variable-name"index="47"length="8">        basePath      </node><!-- name="server-variable-name"-->    </node><!-- name="server-variable"-->  </node><!-- name="server-url-template"--></root>

NOTE: AST can also be traversed in classical way usingdepth first traversal. For more information about this option please refer toapg-js andapg-js-examples.

Validation

Validating a Server URL Templating is as simple as importing thetest function and calling it.

import{test}from'openapi-server-url-templating';test('https://{username}.gigantic-server.com:{port}/{basePath}');// => truetest('https://gigantic-server.com/base-path');// => truetest('https://gigantic-server.com/base-path',{strict:true});// => false (doesn't contain any server-variable)

Substitution

Performing Server URL template substitution is as simple as importing thesubstitute function and calling it.

import{substitute}from'openapi-server-url-templating';subtitute('https://{username}.gigantic-server.com',{username:'char0n'});// => "https://char0n.gigantic-server.com"

Substituted Server URL Templating is automatically encoded usingencodeURIComponent function.It is possible to provide a custom encoder.

import{substitute}from'openapi-server-url-templating';substitute('https://{username}.gigantic-server.com',{username:'/?#'},{encoder:(serverVariable)=>serverVariable,// no encoding});// => "https:///?#.gigantic-server.com"

Grammar

New grammar instance can be created in following way:

import{Grammar}from'openapi-server-url-templating';constgrammar=newGrammar();

To obtain original ABNF (SABNF) grammar as a string:

import{Grammar}from'openapi-server-url-templating';constgrammar=newGrammar();grammar.toString();// orString(grammar);

More about OpenAPI Server URL Templating

The Server URL Templating is defined by the followingABNF syntax

; OpenAPI Server URL templating ABNF syntaxserver-url-template=1*(literals/server-variable ); variant of https://www.rfc-editor.org/rfc/rfc6570#section-2server-variable="{"server-variable-name"}"server-variable-name=1*( %x00-7A/ %x7C/ %x7E-10FFFF ); every UTF8 character except { and } (from OpenAPI); https://www.rfc-editor.org/rfc/rfc6570#section-2.1; https://www.rfc-editor.org/errata/eid6937literals=1*( %x21/ %x23-24/ %x26-3B/ %x3D/ %x3F-5B/ %x5D/ %x5F/ %x61-7A/ %x7E/ucschar/iprivate/pct-encoded); any Unicode character except: CTL, SP,;  DQUOTE, "%" (aside from pct-encoded),;  "<", ">", "\", "^", "`", "{", "|", "}"; https://www.rfc-editor.org/rfc/rfc6570#section-1.5DIGIT=  %x30-39; 0-9HEXDIG=DIGIT/"A"/"B"/"C"/"D"/"E"/"F"; case-insensitivepct-encoded="%"HEXDIGHEXDIGucschar=  %xA0-D7FF/ %xF900-FDCF/ %xFDF0-FFEF/  %x10000-1FFFD/ %x20000-2FFFD/ %x30000-3FFFD/  %x40000-4FFFD/ %x50000-5FFFD/ %x60000-6FFFD/  %x70000-7FFFD/ %x80000-8FFFD/ %x90000-9FFFD/  %xA0000-AFFFD/ %xB0000-BFFFD/ %xC0000-CFFFD/  %xD0000-DFFFD/ %xE1000-EFFFDiprivate=  %xE000-F8FF/ %xF0000-FFFFD/ %x100000-10FFFD

License

openapi-server-url-templating is licensed underApache 2.0 license.openapi-server-url-templating comes with an explicitNOTICE filecontaining additional legal notices and information.