5.4 API documents

Dataway generates standard documents for published, enabled APIs, ready for tools such as Swagger UI. Republishing, disabling or deleting an API updates the document.

Supported standards

Standard	Default URL
OpenAPI 3.2.1	/docs/openapi.json
Swagger 2.0	/docs/swagger2.json

Both endpoints return JSON and support GET and HEAD. Use OpenAPI for definitions Swagger 2.0 cannot represent, including oneOf, multi-type schemas and TRACE.

Enable and retrieve

Enable the endpoint with dataway.docs-enabled and set its prefix with dataway.docs-prefix. For Spring:

application.yml

dataway:
  docs-enabled: true
  docs-prefix: /docs

Requests require Operation.DOCUMENT permission. Download a document using cookies saved after login:

Download the OpenAPI document

curl -b cookies.txt http://127.0.0.1:8080/docs/openapi.json -o openapi.json

See DatawayConfig for title, API version and public API URL settings.

Swagger UI preview

All three framework examples provide /swagger/index.html. After login, expand an API, click Try it out, enter parameters and click Execute to view the request and response.