Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/swaggerexpert/openapi-server-url-templating
OpenAPI Server URL templating parser, validator and substitution mechanism.
https://github.com/swaggerexpert/openapi-server-url-templating
openapi3 openapi31 server substitution templating url
Last synced: 2 months ago
JSON representation
OpenAPI Server URL templating parser, validator and substitution mechanism.
- Host: GitHub
- URL: https://github.com/swaggerexpert/openapi-server-url-templating
- Owner: swaggerexpert
- License: apache-2.0
- Created: 2024-06-03T08:05:16.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2024-10-23T22:56:25.000Z (3 months ago)
- Last Synced: 2024-10-24T12:06:04.606Z (3 months ago)
- Topics: openapi3, openapi31, server, substitution, templating, url
- Language: JavaScript
- Homepage:
- Size: 612 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Governance: GOVERNANCE.md
Awesome Lists containing this project
README
# openapi-server-url-templating
[](https://www.npmjs.com/package/openapi-server-url-templating)
[](https://www.npmjs.com/package/openapi-server-url-templating)
[](https://github.com/swaggerexpert/openapi-server-url-templating/actions)
[](https://dependabot.com/)
[](https://npm.runkit.com/openapi-server-url-templating)
[](https://tidelift.com/subscription/pkg/npm-openapi-server-url-templating?utm_source=npm-openapi-server-url-templating&utm_medium=referral&utm_campaign=readme)
[Server URL Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-object) supports [Server Variables](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-variable-object). Variable substitutions will be made when a variable is named in `{`brackets`}`.
This mechanism is used by [Server Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-object)
of [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification).
`openapi-server-url-templating` is a **parser**, **validator** and **substitution mechanism** for OpenAPI Server URL Templating. It supports
Server Object URL Templating defined in following OpenAPI specification versions:
- [OpenAPI 3.0.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#server-object)
- [OpenAPI 3.0.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md#server-object)
- [OpenAPI 3.0.2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#server-object)
- [OpenAPI 3.0.3](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#server-object)
- [OpenAPI 3.1.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#server-object)
Get professionally supported openapi-server-url-templating with Tidelift Subscription.
## Table of Contents
- [Getting started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Extraction](#extraction)
- [Parsing](#parsing)
- [Validation](#validation)
- [Substitution](#substitution)
- [Grammar](#grammar)
- [More about OpenAPI Server URL Templating](#more-about-openapi-server-url-templating)
- [License](#license)
## Getting started
### Installation
You can install `openapi-server-url-templating` using `npm`:
```sh
$ npm install openapi-server-url-templating
```
### Usage
`openapi-server-url-templating` currently supports **parsing**, **validation** and **substitution**.
Both parser and validator are based on a superset of [ABNF](https://www.rfc-editor.org/rfc/rfc5234) ([SABNF](https://cs.github.com/ldthomas/apg-js2/blob/master/SABNF.md))
and use [apg-lite](https://github.com/ldthomas/apg-lite) parser generator.
#### Parsing
Parsing a Server URL Templating is as simple as importing the **parse** function
and calling it.
```js
import { parse } from 'openapi-server-url-templating';
const parseResult = 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
```js
import { parse } from 'openapi-server-url-templating';
const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
const parts = [];
parseResult.ast.translate(parts);
```
After running the above code, **parts** variable has the following shape:
```js
[
[
'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
```js
import { parse } from 'openapi-server-url-templating';
const parseResult = parse('https://{username}.gigantic-server.com:{port}/{basePath}');
const xml = parseResult.ast.toXml();
```
After running the above code, **xml** variable has the following content:
```xml
https://{username}.gigantic-server.com:{port}/{basePath}
https://{username}.gigantic-server.com:{port}/{basePath}
https://
{username}
username
.gigantic-server.com:
{port}
port
/
{basePath}
basePath
```
> NOTE: AST can also be traversed in classical way using [depth first traversal](https://www.tutorialspoint.com/data_structures_algorithms/depth_first_traversal.htm). For more information about this option please refer to [apg-js](https://github.com/ldthomas/apg-js) and [apg-js-examples](https://github.com/ldthomas/apg-js-examples).
#### Validation
Validating a Server URL Templating is as simple as importing the **test** function and calling it.
```js
import { test } from 'openapi-server-url-templating';
test('https://{username}.gigantic-server.com:{port}/{basePath}'); // => true
test('https://gigantic-server.com/base-path'); // => true
test('https://gigantic-server.com/base-path', { strict: true }); // => false (doesn't contain any server-variable)
```
#### Substitution
Substituting a Server URL Templating is as simple as importing the **substitute** function and calling it.
```js
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 using [encodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) function.
It is possible to provide a custom encoder.
```js
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:
```js
import { Grammar } from 'openapi-server-url-templating';
const grammar = new Grammar();
```
To obtain original ABNF (SABNF) grammar as a string:
```js
import { Grammar } from 'openapi-server-url-templating';
const grammar = new Grammar();
grammar.toString();
// or
String(grammar);
```
## More about OpenAPI Server URL Templating
The Server URL Templating is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax
```abnf
; OpenAPI Server URL templating ABNF syntax
server-url-template = 1*( literals / server-variable )
server-variable = "{" server-variable-name "}"
server-variable-name = 1*( unreserved / pct-encoded / sub-delims / ":" / "@" )
literals = 1*( %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
/ %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
/ pct-encoded)
; any Unicode character except: CTL, SP,
; DQUOTE, "'", "%" (aside from pct-encoded),
; "<", ">", "\", "^", "`", "{", "|", "}"
; Characters definitions (from RFC 6570)
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DIGIT = %x30-39 ; 0-9
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
; case-insensitive
pct-encoded = "%" HEXDIG HEXDIG
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
ucschar = %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-EFFFD
iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD
```
## License
`openapi-server-url-templating` is licensed under [Apache 2.0 license](https://github.com/swaggerexpert/openapi-server-url-templating/blob/main/LICENSE).
`openapi-server-url-templating` comes with an explicit [NOTICE](https://github.com/swaggerexpert/openapi-server-url-templating/blob/main/NOTICE) file
containing additional legal notices and information.