improve docs, add release note #12439

Author: pdurbin

doc/release-notes/12439-openapi.md

@@ -0,0 +1,7 @@
+## Updates for API Users
+
+- The quality of the OpenAPI document has been greatly improved, increasing from 10/100 to 98/100 according [vacuum](https://quobix.com/vacuum/). See [the guides](https://dataverse-guide--12439.org.readthedocs.build/en/12439/api/getting-started.html#getting-the-openapi-document) and #12439.
+
+## Updates for Developers
+
+- If you are adding or updating Dataverse APIs you are now required to add OpenAPI annotations. See [the guides](https://dataverse-guide--12439.org.readthedocs.build/en/12439/developers/api-design.html#openapi) and #12439.

doc/sphinx-guides/source/api/getting-started.rst

@@ -178,7 +178,9 @@ 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.
+If you have feedback about the our OpenAPI document, please contact us through the usual channels under :ref:`getting-help-with-apis`.
+
+You can find more information about validating the document under :ref:`openapi-dev` in the Developer Guide.
 
 Beyond "Getting Started" Tasks
 ------------------------------

doc/sphinx-guides/source/developers/api-design.rst

@@ -14,13 +14,39 @@ 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.
+OpenAPI Annotations
+~~~~~~~~~~~~~~~~~~~
+
+To keep our OpenAPI document at a reasonable quality, you must add annotations to API endpoints you are adding and editing. Here's an example:
+
+.. code-block:: java
+
+    @POST
+    @AuthRequired
+    @Path("/")
+    @Operation(summary = "Creates a license", description = "Creates a license when the authenticated user is a superuser and returns the created license location.")
+    @APIResponse(responseCode = "201", description = "License created with a Location header pointing to the new license.")
+    public Response addLicense(@Context ContainerRequestContext crc,
+            @RequestBody(description = "License definition to persist, including name, URI, active state, and sort order.",
+                    content = @Content(mediaType = "application/json",
+                            schema = @Schema(type = SchemaType.OBJECT,
+                                    description = "License definition accepted by the license administration API.")))
+            License license) {
+    ...
+    }
+
+If you are looking for a reference about the annotations used to generate the OpenAPI document, you can find it in the `MicroProfile OpenAPI Specification <https://download.eclipse.org/microprofile/microprofile-open-api-3.1/microprofile-openapi-spec-3.1.html#_detailed_usage_of_key_annotations>`_.
+
+OpenAPI Quality
+~~~~~~~~~~~~~~~
+
+To use `vacuum <https://quobix.com/vacuum/>`_ with our recommended settings to check the quality of our OpenAPI document, see the :download:`README.md <../../../../scripts/openapi/README.md>` under ``scripts/openapi``.
 
 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.
-
-If you are looking for a reference about the annotations used to generate the OpenAPI document, you can find it in the `MicroProfile OpenAPI Specification <https://download.eclipse.org/microprofile/microprofile-open-api-3.1/microprofile-openapi-spec-3.1.html#_detailed_usage_of_key_annotations>`_.
+- Check that HTTP GET and DELETE operations do not accept request bodies.
+- Various notes under :download:`vacuum-recommended.yaml <../../../../scripts/openapi/vacuum-recommended.yaml>`.
 
 Paths
 -----

scripts/openapi/vacuum-recommended.yaml

@@ -9,11 +9,11 @@ rules:
   oas3-missing-example: false
   # We have /pids/{id}/delete --> see edu.harvard.iq.dataverse.api.Pids#deletePid
   # The HTTP verb there is DELETE so actually we don't need to have the verb in the path,
-  #  could be fixed
+  # could be fixed.
   no-http-verbs-in-path: false
   # These endpoints have an unused `body` parameter, probably because of copy-paste.
   # no-request-body: false would not report them, but rather we should fix them to remove `body`
   # GET /files/{id}/prov-freeform
   # GET /files/{id}/prov-json
   # GET /files/{id}/prov-json
-  #no-request-body: false
+  #no-request-body: false