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.
WARNING
A lot of this documentation is deprecated. The host location as well as authentication method (token vs cookie) is outdated. This addon is a candidate for deprecation so I'm not going to spend time updating the documentation unless we plan to support this in the future.
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.