stub out guidance on openapi validation #9981 #10236

IQSS · May 29, 2024 · 4ea444a · 4ea444a
1 parent f265744
commit 4ea444a
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 3 deletions.
diff --git 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
@@ -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
 -----