Philip Durbin π (Oct 18 2024 at 13:38): Philip Durbin π (Oct 18 2024 at 13:38):@Jan Range in the docs meeting I just mentioned the API docs you generated using OpenAPI and https://readme.com
Philip Durbin π (Oct 18 2024 at 13:39):Do you still have an example up somewhere?
Jan Range (Oct 18 2024 at 13:42):Of course, you can find the example here - https://test-dv.readme.io
Dieuwertje Bloemen (Oct 18 2024 at 13:43):wow, that looks great!
Jan Range (Oct 18 2024 at 13:44):I agree, its really nice! You can also test/run the endpoints
Dieuwertje Bloemen (Oct 18 2024 at 13:51):This non-developer is very happy to see that :sweat_smile:
Vaida PlankytΔ π¨ (Oct 18 2024 at 13:56):this looks so cool! love the ability to edit the variables in an API call directly from the interface, makes that really clear for people. we discussed having this kind of API docs in the docs meeting today, to remove manual error/inconsistencies and have more automated updating.
Philip Durbin π (Oct 18 2024 at 15:53):It's extremely cool. Thanks, @Jan Range! 
Philip Durbin π (Oct 18 2024 at 15:54):I'm slightly bummed that if I click "try it" at https://test-dv.readme.io/reference/getversioninfo it complains that I need an API token. It's an open API that doesn't require auth: https://demo.dataverse.org/api/v1/info/version
Jan Range (Oct 18 2024 at 16:07):Yes, that is a bit annoying. This stems from the OpenAPI specs though, because I have added the TokenAuth globally to use endpoints that do require auth. You can add the security scheme per endpoint though and then it shouldnt be mandatory anymore for all of them
Philip Durbin π (Oct 18 2024 at 16:08):I see. @Juan Pablo Tosca Villanueva do you happen to know what we should add on the Java side?
Juan Pablo Tosca Villanueva (Oct 18 2024 at 17:36):I will figure it out, but will it work even if it is set globally ? @Jan Range ?
Juan Pablo Tosca Villanueva (Oct 18 2024 at 17:36):Like if you set it globally and then some endpoints are just marked as secured
Juan Pablo Tosca Villanueva (Oct 18 2024 at 17:37):I wonder how it will work or should work with endpoints that return different things depending on auth
Philip Durbin π (Oct 18 2024 at 17:54):We already put @AuthRequired on all the endpoints that require auth, if that helps.
Jan Range (Oct 19 2024 at 08:30):@Juan Pablo Tosca Villanueva yes you can define a global auth scheme and then assign it to each endpoint that requires it. It is also possible to render auth optional, using the following on an endpoint:
security:
- {}
- api_key: []
Jan Range said:
Juan Pablo Tosca Villanueva yes you can define a global auth scheme and then assign it to each endpoint that requires it. It is also possible to render auth optional, using the following on an endpoint:
security: - {} - api_key: []
I have to start making merits so @Jan Range mentions me on the next DV community meeting :sweat_smile: , would this be what we need for this to work correctly? "https://github.com/IQSS/dataverse/pull/10971" sample:
post:
tags:
- saveAuxiliaryFileWithVersion
summary: Save auxiliary file with version
description: Saves an auxiliary file
operationId: Access_saveAuxiliaryFileWithVersion
parameters:
- name: fileId
in: path
required: true
schema:
format: int64
type: integer
- name: formatTag
in: path
required: true
schema:
type: string
- name: formatVersion
in: path
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
type: string
responses:
"200":
description: File saved response
"403":
description: User not authorized to edit the dataset.
"400":
description: File not found based on id.
security:
- api_token: []
@Philip Durbin π
Juan Pablo Tosca Villanueva (Oct 25 2024 at 15:42):We would need to add the annotation Β @SecurityRequirement(name = "api_token") to each secured endpoint and then disable the global one is my guess.
Juan Pablo Tosca Villanueva (Oct 25 2024 at 16:23):I think we also need to define the:
"securitySchemes" : {
"api_key" : {
"type" : "apiKey",
"name" : "api_key",
"scheme" : "api_key"
}
}
Still trying to figure it out how to do it for microprofile
Juan Pablo Tosca Villanueva (Nov 01 2024 at 20:36):I am so close...
Juan Pablo Tosca Villanueva (Nov 01 2024 at 20:36):
Notification Bot (Nov 01 2024 at 20:37):2 messages were moved here from #dev > Zed by Philip Durbin π.
Jan Range (Nov 06 2024 at 06:38):@Juan Pablo Tosca Villanueva that looks promising! Looking forward to the result
Philip Durbin π (Nov 06 2024 at 13:56):@Jan Range he's talking about the hub, not Dataverse: https://github.com/IQSS/dataverse-hub
I wouldn't want to get your hopes up. :sweat_smile:
Juan Pablo Tosca Villanueva (Nov 06 2024 at 14:21):But it may pave the path to do this on DV one day in the future :wink:
Juan Pablo Tosca Villanueva (Nov 26 2024 at 20:34):I am/was looking at this today, the documentation I made for the hub was done with SpringDoc (to generate) and Swagger tags to define the documentation, it seems that smallrye (generator) favors the use of the eclipse microprofile tags for definition of the documentation. Which makes it awkward because A LOT of the annotations share the same exact same name, and let's say 95% of the properties but there are small differences that make them not compatible between the two of them.
Juan Pablo Tosca Villanueva (Nov 26 2024 at 20:35):For example this issue is something that is also preventing me from defining this global security schema: https://stackoverflow.com/questions/78701162/generating-openapi-with-eclipse-microprofile-annotations-how-to-configure-globa
Juan Pablo Tosca Villanueva (Nov 26 2024 at 20:36):I probably could try to make a demo with SpringDocs + Swagger annotations but I am not sure if any of you guys have hard set opinions on one or the other... (looks at @Oliver Bertuch) :eyes:
Juan Pablo Tosca Villanueva (Nov 26 2024 at 20:37):TLDR: [Spring docs + Swagger tags] vs [Smallrye + Microprofile]
Juan Pablo Tosca Villanueva (Nov 26 2024 at 20:44):We could also look at a third option that is removing the generator and see what payara likes...
Philip Durbin π (Nov 26 2024 at 20:59):Maybe we could experiment in a couple branches with different solutions.
Philip Durbin π (Apr 11 2025 at 13:54):How does this look?
/info/applicationTermsOfUse:
get:
tags:
- info
operationId: Info_getApplicationTermsOfUse
parameters:
- name: lang
in: query
description: Two-character language code.
required: false
schema:
type: string
example: en
responses:
"200":
description: Application Terms of Use (General Terms of Use) that must be
agreed to at signup.
That's from this commit: https://github.com/IQSS/dataverse/pull/11422/commits/26b9be752c0603ef7689244b5d2bab4c1e88f8de
Philip Durbin π (Apr 11 2025 at 13:55):@Jan Range @Juan Pablo Tosca Villanueva ^^
Philip Durbin π (Jul 13 2026 at 18:13):A while back @Jan Range created https://test-dv.readme.io to show us how to created API docs based on /openapi output. It's awesome. :tada:
I just merged #12439 by @BalΓ‘zs Pataki (#dev > Improve OpenAPI descriptions with AI) which results in Dataverse APIs emitting a lot more detail via /openapi.
@Jan Range would it be easy for you to make a new build of the readme.io docs?
Jan Range (Jul 13 2026 at 19:54):Is it already in the new version? Afaik you can either upload a new spec or point to one
Philip Durbin π (Jul 13 2026 at 19:55):It's already merged so yeah, it's in there.
Jan Range (Jul 13 2026 at 20:42):Is it on demo.dataverse.org already? If so, I could simply point it to the OpenAPI endpoint
Philip Durbin π (Jul 13 2026 at 20:44):No, but it will be on beta.dataverse.org when we resolve this: https://github.com/IQSS/dataverse/issues/12531
Philip Durbin π (Jul 13 2026 at 20:46):(demo tracks the latest release. beta tracks the latest merged into the "develop" branch.)
Philip Durbin π (Jul 13 2026 at 20:49):For now I put it here: https://dev1.dataverse.org/openapi?format=json
Jan Range (Jul 13 2026 at 20:56):Thanks! Should be updated now on https://test-dv.readme.io/
Jan Range (Jul 13 2026 at 21:18):One thing that the OpenAPI spec would require is to include either the host server of an instance, if one wants to host the docs for their own instance, or to default to demo.dataverse.org. Adding the following to the OpenAPI fixes it, because otherwise it defaults to example.com and that breaks the "Try it" button:
"servers" : [ {
"url" : "https://{dataverseHost}/api",
"description" : "Default Dataverse API server (demo.dataverse.org) with overridable host.",
"variables" : {
"dataverseHost" : {
"default" : "demo.dataverse.org",
"description" : "Dataverse host name. Replace with another installation to target a different server."
}
}
} ],
Philip Durbin π said:
No, but it will be on beta.dataverse.org when we resolve this: https://github.com/IQSS/dataverse/issues/12531
Fixed: https://beta.dataverse.org/openapi?format=json
Philip Durbin π (Jul 15 2026 at 20:58):@BalΓ‘zs Pataki in the last minutes of today's pyDataverse meeting (recording) we talked about how @Jan Range rebuilt https://test-dv.readme.io with the latest /openapi data but there are still some shortcomings from a docs perspective.
Philip Durbin π (Jul 16 2026 at 20:12):I just tried https://test-dv.readme.io/reference/dataverses_updateattribute and it worked! What a nice tool!
Philip Durbin π (Jul 16 2026 at 21:03):It inspired me to announce https://test-dv.readme.io , even though it still has test in the name: https://groups.google.com/g/dataverse-community/c/AlEnUKa6K5U/m/aFk6lhIwAgAJ :smile:
Last updated: Aug 18 2026 at 08:27 UTC