From 4ea444a51cfa7cad5d56c477bcfa1baae016cb87 Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Wed, 29 May 2024 15:12:08 -0400 Subject: [PATCH] stub out guidance on openapi validation #9981 #10236 --- doc/sphinx-guides/source/api/getting-started.rst | 10 +++++++--- doc/sphinx-guides/source/developers/api-design.rst | 13 +++++++++++++ 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/doc/sphinx-guides/source/api/getting-started.rst b/doc/sphinx-guides/source/api/getting-started.rst index e77706a1b9b..3f93f4ac444 100644 --- a/doc/sphinx-guides/source/api/getting-started.rst +++ b/doc/sphinx-guides/source/api/getting-started.rst @@ -156,10 +156,12 @@ See :ref:`list-role-assignments-on-a-dataverse-api`. .. _openapi: -Getting the OpenAPI Specification ---------------------------------- +Getting the OpenAPI Document +---------------------------- + +You can access our `OpenAPI document`_ using the ``/openapi`` endpoint. The default format is YAML if no parameter is provided, but you can also obtain the JSON version by either passing ``format=json`` as a query parameter or by sending ``Accept:application/json`` (case-sensitive) as a header. -You can access our OpenAPI specification using the ``/openapi`` endpoint. The default format is YAML if no parameter is provided, but you can also obtain the JSON version by either passing ``format=json`` as a query parameter or by sending ``Accept:application/json`` (case-sensitive) as a header. +.. _OpenAPI document: https://spec.openapis.org/oas/latest.html#openapi-document .. note:: See :ref:`curl-examples-and-environment-variables` if you are unfamiliar with the use of export below. @@ -176,6 +178,8 @@ The fully expanded example above (without environment variables) looks like this curl "https://demo.dataverse.org/openapi?format=json" +We are aware that our OpenAPI document is not perfect. You can find more information about validating the document under :ref:`openapi-dev` in the Developer Guide. + Beyond "Getting Started" Tasks ------------------------------ diff --git a/doc/sphinx-guides/source/developers/api-design.rst b/doc/sphinx-guides/source/developers/api-design.rst index e7a7a6408bb..ac30644d1a5 100755 --- a/doc/sphinx-guides/source/developers/api-design.rst +++ b/doc/sphinx-guides/source/developers/api-design.rst @@ -7,6 +7,19 @@ API design is a large topic. We expect this page to grow over time. .. contents:: |toctitle| :local: +.. _openapi-dev: + +OpenAPI +------- + +As you add API endpoints, please be conscious that we are exposing these endpoints as an OpenAPI document at ``/openapi`` (e.g. http://localhost:8080/openapi ). See :ref:`openapi` in the API Guide for the user-facing documentation. + +We've played around with validation tools such as https://quobix.com/vacuum/ and https://pb33f.io/doctor/ only to discover that our OpenAPI output is less than ideal, generating various warnings and errors. + +You can prevent additional problems in our OpenAPI document by observing the following practices: + +- When creating a method name within an API class, make it unique. + Paths -----