Import Swagger api documentation to Ardoq
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
dev
resources
src/ardoq
test
.gitignore
Dockerfile
LICENSE
README.md
build.xml
project.clj
release.sh

README.md

Ardoq Open API (Swagger) Addon

This addon lets you import Open API documentation to Ardoq. It has a built in page it uses as a gui that can be rendered through http://base-url/

The gui itself then has one simple function in gathering required data field for the post, which imports the Open API documentation.

Posting to the addon

The addon has a single POST api call which can be used to import data to Ardoq. So by calling a POST on http://swagger.addon.ardoq.com/import there is the possibility of posting directly to Ardoq.

To post to the api the following data is required in the post as params.

  • spec - This overrides the url and should contain a full Open API specification. If one wants to use an url instead this should be omitted
  • url - This is used to fetch an api if a specification is not provided in the params
  • wsname - Used as the name for a workspace. Can be left blank if one wants to use the name in the swagger specification.
  • headers - Optional headers. Can be used to validate access to an url if needed.
  • ignorer - Determines if the validator should be ignored. Can contain any value if one wants to ignore the validation.
  • org - Name of organization one wishes to import to
  • token - API token generated by ardoq
  • ardoq-base-url - If your Ardoq account is on a custom domain, you muse provide the URL.

This should then create or update a workspace from the specification provided.

An example curl command with an url

curl -F"url=<URL to your specification>" -F"org=<my-org>" -F"token=<my-token>" https://swagger.addon.ardoq.com/import

An example of a curl with a specification. note the < in swag=< in front of the file name. This < needs to be there, and will add the content of the file to the request!

curl -F"swag=<{my-specification.yaml}" -F"org={my-org}" -F"token={my-token}" https://swagger.addon.ardoq.com/import

Running the addon in Docker

docker run -e API_BASE_URL=https://app.ardoq.com -d --name="swagger" ardoq/ardoq-swagger-addon:latest

You can replace the API_BASE_URL with the URL to your own installation if you run locally, or on premise.

Examples

The tests import sample files from APIs.guru - Wikipedia for Web APIs, specifically through the API endpoint.