windomz / swagger-merger Goto Github PK
View Code? Open in Web Editor NEW:link: Merge multiple swagger files into a swagger file, support JSON/YAML.
License: MIT License
:link: Merge multiple swagger files into a swagger file, support JSON/YAML.
License: MIT License
Dockerfile which was added in #69 and #70 installs swagger-merger
NPM package:
Line 3 in 860e4ea
It is probably the most efficient way to build a Docker image around swagger-merger
, but it leaves a lot to be desired. For example, how would someone build a swagger-merger
Docker image with the latest features from GitHub repo, from a branch, from a fork, with changes from someone's local working directory?
There should be a Dockerfile that allows building image from source code checkout instead of relying on NPM.
Thank you for creating this package, it saves me a lot of time.
Usecase: Where I have a legacy swagger.json
. And now I just want to add new paths/def using swagger-merger
instead of editing old file.
Example:
// apis.swagger.json
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Echo",
"description": "#### Echos back every URL, method, parameter and header\nFeel free to make a path or an operation and use **Try Operation** to test it. The echo server will\nrender back everything.\n"
},
"schemes": [
"http"
],
"$ref": "./host.yaml",
"basePath": "/echo",
"paths": {
"/": {
"get": {
"responses": {
"$ref": "./responses.json#/components/root/get"
}
},
"post": {
"responses": {
"$ref": "./responses.json#/components/root/post"
},
"parameters": [
{
"$ref": "./name.json"
},
{
"$ref": "./year.json"
}
]
}
}
}
}
// index.json
{
"$ref": "apis.swagger.json",
"paths": {
"/test-path/{id}": {
"parameters": [
{
"$ref": "./id.json"
}
],
"get": {
"responses": {
"$ref": "./responses.json#/components/test-path"
}
}
}
}
}
Expected:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Echo",
"description": "#### Echos back every URL, method, parameter and header\nFeel free to make a path or an operation and use **Try Operation** to test it. The echo server will\nrender back everything.\n"
},
"schemes": [
"http"
],
"$ref": "./host.yaml",
"basePath": "/echo",
"paths": {
"/": {
"get": {
"responses": {
"$ref": "./responses.json#/components/root/get"
}
},
"post": {
"responses": {
"$ref": "./responses.json#/components/root/post"
},
"parameters": [
{
"$ref": "./name.json"
},
{
"$ref": "./year.json"
}
]
}
},
"/test-path/{id}": {
"parameters": [
{
"$ref": "./id.json"
}
],
"get": {
"responses": {
"$ref": "./responses.json#/components/test-path"
}
}
}
}
}
Is there anyway to achieve this?
Or when do you plan to support merging of multiple independent yaml files? i.e. my cli should accept multiple yaml files or *.yaml as input and do the job.
How can i run ir inside javascript code not user child_process exec and not install globally?
const swaggerMerger = require('swagger-merger');
swaggerMerger ....
I try to merge several Swagger files into one but facing the problem that the resulting Swagger file reflects an list of definitions as an array instead of a combined object, is this by design or is it a bug? The OpenAPI 2.0 specifies that the "definitions" block should be an object.
Config:
definitions:
- $ref: "./file1.json#definitions"
- $ref: "./file2.json#definitions"
Actual output:
{
"definitions": [
{
"file1Definition1": "...",
"file1Definition2": "..."
},
{
"file2Definition1": "...",
"file2Definition2": "..."
}
]
}
Expected output:
{
"definitions":
{
"file1Definition1": "...",
"file1Definition2": "...",
"file2Definition1": "...",
"file2Definition2": "..."
}
}
Switched to this package from openapi-merger
in hope for better, more predictable support of references.
Let's say, you want to have a file per path, like this:
paths:
/users/{id}/profile:
$ref: "./paths/users/{id}/profile.yml"
This is legal, as {
and }
are legal in Linux paths, and in YAML keys and values. However, after running swagger-merger
, the result is just that same $ref
inserted verbatim, without resolving it to the contents of the referenced file.
Looks like curly braces are not supported, which is quite unpredictable.
I'm not a JS expert but in your package.json you require:
"engines": {
"node": ">= 0.6.x"
}
I'm using Debian Stretch with default node version: v4.8.2 (which has no full ES6 Support) but you seem to use ES6 features in this project.
You should fix the required version in package.json to give everyone who uses an outdated version of node a hint why he can't install swagger-merger and avoid that he is getting an error like this:
/usr/local/lib/node_modules/swagger-merger/node_modules/fmtconv/lib/converter.js:19
function fmtconv (input, output, compact = false) {
^
SyntaxError: Unexpected token =
at exports.runInThisContext (vm.js:53:16)
at Module._compile (module.js:373:25)
at Object.Module._extensions..js (module.js:416:10)
at Module.load (module.js:343:32)
at Function.Module._load (module.js:300:12)
at Module.require (module.js:353:17)
at require (internal/module.js:12:17)
at Object.<anonymous> (/usr/local/lib/node_modules/swagger-merger/node_modules/fmtconv/lib/fmtconv.js:6:19)
at Module._compile (module.js:409:26)
at Object.Module._extensions..js (module.js:416:10)
I think at least v6.0.0 should be required.
I'm trying to run a shell script to build a documentation. When I do this I get an error:
xxxxxxxx/node_modules/swagger-merger/bin/swagger-merger.js:27
input: options.input || file || '',
^
TypeError: Cannot read property 'input' of undefined
at Command.program.version.usage.description.option.option.option.option.action (/xxxxxxxxxx/node_modules/swagger-merger/bin/swagger-merger.js:27:22)
at Command.listener (/xxxxxxxxx/node_modules/commander/index.js:315:8)
at Command.emit (events.js:182:13)
at Command.parseArgs (/xxxxxxxxxxx/node_modules/commander/index.js:668:12)
at Command.parse (/xxxxxxxxxxxxx/node_modules/commander/index.js:474:21)
at Object. (/xxxxxxxxxxxxxx/node_modules/swagger-merger/bin/swagger-merger.js:35:9)
at Module._compile (internal/modules/cjs/loader.js:722:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:733:10)
at Module.load (internal/modules/cjs/loader.js:620:32)
at tryModuleLoad (internal/modules/cjs/loader.js:560:12)
If I run the command separately I get:
swagger-merger --debug -i src/swagger/main.yml
Unexpected token [ in JSON at position 3502
what it's not very helpful without the proccessed file. i have like 200
node: 11.3.0
npm: 6.4.1
Thanks in advance
Does this module support typescript?
Importing show warning on my codebase because
Could not find a declaration file for module 'swagger-merger'. '/Users/song/Xendit/nex-api/node_modules/swagger-merger/index.js' implicitly has an 'any' type.
Try `npm i --save-dev @types/swagger-merger` if it exists or add a new declaration (.d.ts) file containing `declare module 'swagger-merger';`ts(7016)
npm i --save-dev @types/swagger-merger
results in NOT FOUND
Given the following input file: in.yaml
description:
$ref: ./desc.yaml#/description
And the following referenced file: desc.yaml
:
description: this is a value
When I merge the input file using swagger-merger -i in.yaml -o out.yaml
Then I receive the following error: Unexpected token } in JSON at position 33
i would like to merge a remote file like
$ref: "https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml"
into my specification and also use the url#/subobject
syntax on it like:
$ref: "https://raw.githubusercontent.com/swagger-api/swagger-codegen/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#/securityDefinitions"
Is it possible to implement this for swagger-merger?
Hello π
As the title says, how about adding Dockerfile and publishing images on DockerHub?
I use swagger-merger with Docker. It compels me to write a Dockerfile for that but it brings a benefit to reuse this library with ease.
I've already created an example repository https://github.com/ohbarye/swagger-merger-docker and published Docker image on https://hub.docker.com/r/ohbarye/swagger-merger though, I think the Dockerfile can be in this repository (if you're willing so).
If you don't like this idea, feel free to close this issue. I know that managing a Docker image needs additional works and a maintainer might suffer.
I tried using this to process a swagger.json file which had refs to a "submodels.json" file. After it is done, the refs are exactly the same.
Hi WindomZ,
First of all, nice work :)
...And then the issue:
On Windows, when you evaluate path.join() the structure will be converted
./responses.yaml#/components/root/get -> .\responses.yaml#\components\root\get
This is Ok, if you want to locate the file, but the splitReference method gets the \components\root\get string so this code is not enugh
if (hashtag.startsWith('/')) {
hashtag = hashtag.slice(1)
}
I would suggest place these 2 lines before this:
//in case of windows operating system
hashtag = hashtag.replace(/\\/g, "/")
Regards, Adam
I am having the following files:
The idea is: in the command description file, for some reasons, the same uri is expanded into 2 different path locations (one is for global access and will be included in one documentation and the second one is for admin and will be included in the admin documentation along with the one from global).
The idea is when merging the files swagger-merger -i ./test-spec.json -o ./test.json, the resulted file contains just one command for the given endpoint (jut put without get) if the same endpoint is found 2 times.
It does not work well even if I change the tags and I name them differently.
If you need more details, just let me know. This feature saves us on big projects with lots of api endpoints to manage in a documentation which is splitted into different small files for easily management.
Regards
Right now, it appears that the merger function returns some sort of promise instead of the dump from the resulting merge. It would be nice if I where able to programmatically retrieve the dump without having to write to a file in the process.
Am I missing an important reason as to why this promise is returned instead of the dump? Is there I way I'm missing to get the dump without writing to a file?
e.g. I would like to be able to use this library like this:
//Merge yaml files
const spec = merger({
input: './src/__docs__/index.yml',
compact: false
})
//Feed directly into swagger
router.get("/", koaSwagger({
routePrefix: "/docs",
specPrefix: "/docs/spec",
swaggerOptions: {spec}
}))
Edit: for now I forked this repo and frankensteined this functionality in, I won't pull request it because all other features of the repo besides what I'm specifically doing is untested and I have reason to believe it won't work at all haha. Thanks for making this project, it helps tidy up code a lot! After using this it feels like $ref#* should be a feature of swagger/openapi officially
Hi @WindomZ, thank you for this package,
i encountered unresolved paths, if they are on the same level as other objects.
For example my swagger yaml definitions are built like the following:
definitions:
options:
type: "object"
properties:
...
next_object:
type:...
if i want to include some external definitions i do it like this:
definitions:
$ref: "./defs.yaml#/definitions"
options:
type: "object"
properties:
...
next_object:
type:...
which is not resolving the path
but if i only have the path in definitions, the path gets resolved:
definitions:
$ref: "./defs.yaml#/definitions"
is it possible to do this somehow ?
Hi,
It seems that the cause is on options.parent.debug instead of options.debug in swagger-merger.js
Regards
Humpf
I get error: Maximum call stack size exceeded
when using v1.5.1+, but it's ok with v1.4.3 and v1.5.0.
This is an example:
paths:
$ref#users-api: https://api.eraofhealth.com/users-api
referencing a remote yaml or json file with or without a file extension works the same
if the remote file doesnt have a file extension the cli replaces the reference with undefined
instead of dereferencing the remote file
Hi,
I have the following:
path.yml
get:
tags:
- "Tag One"
responses:
'200':
description: Just an example of includes
content:
application/json:
schema:
type: array
items:
$ref: './schema.yml#/put'
schema.yml:
base:
type: object
properties:
propOne:
type: string
example: "Example String"
propTwo:
type: integer
example: 0
put:
allOf:
- $ref: '#/base'
- type: object
properties:
undelete:
type: boolean
example: false
reprocess:
type: boolean
example: false
The merger doesn't pull in the base properties which results in the output file referencing something that doesn't exist:
"paths": {
"/some/path": {
"get": {
"tags": [
"Tag One"
],
"responses": {
"200": {
"description": "Just an example of includes",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/base"
},
{
"type": "object"
}
],
"properties": {
"undelete": {
"type": "boolean",
"example": false
},
"reprocess": {
"type": "boolean",
"example": false
}
}
}
}
}
}
}
}
}
}
}
I've included the example files to help solve this issues.
Thanks.
If I run the command
swagger-merger -i petstore.json -o myswagger.json
The content of petstore.json
gets merged/combined into content of myswagger.json
, meaning myswagger.json
should have both.
The content of petstore.json
overwrites/replaces the content of myswagger.json
, meaning the content of myswagger.json
is lost!
I want to merge these files
swagger.yaml
...
paths:
/pets/{id}:
$ref: "./pets.yaml#/paths/~1pets~1{id}"
pets.yaml
paths:
/pets/{id}:
get: ....
delete: ....
This file structure is helpful for maintenance definition file with some IDE.
I use IntelliJ.
InteliJ can render these files Individually like this.
pets.yaml
I can maintenance pets.yaml with same API path in preview screen.
But, swagger-merger will skip merge definition that include {}.
So, I can't use /paths/~1pets~1{id}
for api definition's key
I tried fix this regular expression
swagger-merger/lib/merge_json.js
Line 67 in 24178ab
to
return doc.replace(/\s*("\$ref")( *):( *)"[^"]+"\s*/gm, s => {
Them, I can merge these definitions.
But, I'm not sure if this fix is correct.
I'm sorry I'm not good at English
13.1.0
to 13.2.0
.π¨ View failing branch.
This version is covered by your current version range and after updating it in your project the build failed.
nyc is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.
The new version differs by 17 commits.
29e6f5e
chore(release): 13.2.0
e95856c
chore: Update dependencies. (#978)
921d386
fix: Create directory for merge destination. (#979)
df2730d
feat: Option Plugins (#948)
35cd49a
feat: document the fact that cacheDir is configurable (#968)
ff834aa
feat: avoid hardcoded HOME for spawn-wrap working dir (#957)
35710b1
build: move windows tests to travis (#961)
93cb5c1
tests: coverage for temp-dir changes (#964)
d566efe
test: stop using LAZY_LOAD_COUNT (#960)
f23d474
chore: update stale bot config with feedback (#958)
62d7fb8
chore: slight tweak to position of test
28b6d09
fix: missing command temp-directory (#928)
40afc5f
fix: nyc processing files not covered by include when all
is enabled. (#914)
ba22a26
docs(readme): Update to reflect .nycrc.json support (#934)
2dbb82d
chore: enable probot-stale
There are 17 commits in total.
See the full diff
There is a collection of frequently asked questions. If those donβt help, you can always ask the humans behind Greenkeeper.
Your Greenkeeper Bot π΄
Reference:
# main.yaml
paths:
$ref#reconciliation: "./reconciliation.yaml"
...
# reconciliation.yaml
/mypath/{id}:
post:
...
result
# swagger.yaml
paths:
'/mypath/{id}':
post:
...
The quotes around the path seem to be invalid.
Love the package, it would be great to see it support references to sub elements of a file. Documentation:
https://swagger.io/docs/specification/using-ref/
example
$ref: '../document.json#/myElement'
seems to work for open api 3. Is it "officially supported" or did I just get lucky?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.