{"id":21366852,"url":"https://github.com/acdh-oeaw/openapi4restxq","last_synced_at":"2025-07-13T05:31:10.174Z","repository":{"id":43111468,"uuid":"198640726","full_name":"acdh-oeaw/openapi4restxq","owner":"acdh-oeaw","description":"A BaseX port of openapi4restxq https://gitlab.gwdg.de/subugoe/openapi4restxq","archived":false,"fork":false,"pushed_at":"2024-05-17T15:17:22.000Z","size":2912,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"master_basex","last_synced_at":"2024-05-17T16:34:33.299Z","etag":null,"topics":["basex","openapi","restxq"],"latest_commit_sha":null,"homepage":null,"language":"XQuery","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acdh-oeaw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-24T13:26:35.000Z","updated_at":"2024-05-17T15:17:26.000Z","dependencies_parsed_at":"2024-03-27T16:42:16.378Z","dependency_job_id":"9142497a-091d-49f2-a8f7-37735815cdc7","html_url":"https://github.com/acdh-oeaw/openapi4restxq","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fopenapi4restxq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fopenapi4restxq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fopenapi4restxq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acdh-oeaw%2Fopenapi4restxq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acdh-oeaw","download_url":"https://codeload.github.com/acdh-oeaw/openapi4restxq/tar.gz/refs/heads/master_basex","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225855886,"owners_count":17534968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["basex","openapi","restxq"],"created_at":"2024-11-22T07:16:40.592Z","updated_at":"2024-11-22T07:16:41.343Z","avatar_url":"https://github.com/acdh-oeaw.png","language":"XQuery","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI\n\nOpenAPI (formerly swagger) is a standard for REST-API documentation and so\noptimized to describe standardized communication with HTTP.\n\n## RESTXQ\n\n[RESTXQ](http://exquery.github.io/exquery/exquery-restxq-specification/restxq-1.0-specification.html)\nis the implementation of well-known function annotations in [XQuery](https://www.w3.org/TR/xquery-31/).\n\n## OpenAPI for RESTXQ\n\nThis is a BaseX port of the original [exist-db version](https://gitlab.gwdg.de/subugoe/openapi4restxq).\n\nThis software combines the power of function annotation in XQuery to prepare an\nOpenAPI conform documentation. It covers the RESTXQ annotations as well as the\n[XQSuite](http://exist-db.org/exist/apps/doc/xqsuite.xml) annotations and uses\n[xqDocs](http://xqdoc.org/xqdoc_comments_doc.html) for describing the API.\n(Note that this does not mean XQSuite works in BaseX. That would need to be ported separately.)\n\nYou can use your own annotation namespace for :args, :assertEquals, :consumes and :produces if you\nsee unwanted side effects. %test has no meaning out of the box for BaseX.\n\nIt is meant to be cloned into a `webapp` RESTXQ directory of a [BaseX](http://basex.org)\nsetup. `content/openapi.xqm` is a self contained module that can be copied into your project's directory.\n\n## Build\n\nIf you want to use swagger-ui (a ready-to-use documentation in HTML) you have to\nload the swagger-ui package before:\n\n```bash\nyarn install\n```\n\n## Install\n\nIf you have the contents of this repository in your RESTXQ path (`webapp` by default) you have access to\nswagger-ui using the `/openapi` URL.\n\n## Use\n\n### Integrated in own applications\n\n* `repo.xml`\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cmeta xmlns=\"http://exist-db.org/xquery/repo\"\u003e\n    \u003cdescription\u003eDescribe your project\u003c/description\u003e\n    \u003cauthor\u003eYour Name\u003c/author\u003e\n    \u003cwebsite\u003eurn:yourprojects_website\u003c/website\u003e\n    \u003cstatus\u003edevelopment\u003c/status\u003e\n    \u003clicense ref=\"https://spdx.org/licenses/\"\u003eMIT\u003c/license\u003e\n    \u003ccopyright\u003etrue\u003c/copyright\u003e\n    \u003ctype\u003eapplication\u003c/type\u003e\n    \u003ctarget\u003eyourproject\u003c/target\u003e\n    \u003cchangelog\u003e\n      \u003cchange version=\"0.3.0\"\u003e\n        \u003cul xmlns=\"http://www.w3.org/1999/xhtml\"\u003e\n          \u003cli class=\"feat\"\u003eFeatures\n            \u003cul style=\"margin-left: 15px;\"\u003e\n              \u003cli\u003eChanged sth.\u003c/li\u003e\n              \u003cli\u003eChanged sth. else\u003c/li\u003e\n              \u003cli\u003eYet another change\u003c/li\u003e\n            \u003c/ul\u003e\n          \u003c/li\u003e\n        \u003c/ul\u003e\n      \u003c/change\u003e\n    \u003c/changelog\u003e\n\u003c/meta\u003e\n```\n\nYou need some info XML files:\n\n* `expath-pkg.xml`\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cpackage xmlns=\"http://expath.org/ns/pkg\"\n  name=\"urn:yourproject\"\n  abbrev=\"yourproj\"\n  version=\"0.3.0\"\n  spec=\"1.0\"\n  xml:id=\"yourprojid\"\u003e\n  \u003ctitle\u003eProject title\u003c/title\u003e\n  \u003cdependency processor=\"http://basex.org\" semver-min=\"9.2\"/\u003e\n  \u003cxquery\u003e\n    \u003cnamespace\u003eurn:yourproject\u003c/namespace\u003e\n    \u003cfile\u003eyourmodule.xqm\u003c/file\u003e\n  \u003c/xquery\u003e\n\u003c/package\u003e\n```\n\n* `openapi-config.xml`\n\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003cconfig xmlns=\"https://lab.sub.uni-goettingen.de/restxqopenapi\"\u003e\n  \u003cinfo\u003e\n  \u003ctermsOfService\u003ehttps://example.com/terms-of-use\u003c/termsOfService\u003e\n  \u003ccontact\u003e\n      \u003cemail\u003einfo@example.com\u003c/email\u003e\n  \u003c/contact\u003e\n  \u003c/info\u003e\n  \u003cservers\u003e\n    \u003cserver url=\"http://localhost:8984/\"\u003eLocal development server\u003c/server\u003e\n    \u003cserver url=\"https://example.com/\"\u003eProduction server\u003c/server\u003e\n  \u003c/servers\u003e\n  \u003ctags\u003e\n    \u003ctag name=\"category1\" method=\"exclusive\"\u003e\n        You can sort your functions into categories using these tags here.\n        \u003cfunction name=\"yourproj:func1\"/\u003e\n        \u003cfunction name=\"yourproj:func2\"/\u003e\n    \u003c/tag\u003e\n    \u003ctag name=\"category\" method=\"exclusive\"\u003e\n        Another category\n        \u003cfunction name=\"yourproj:func3\"/\u003e\n    \u003c/tag\u003e\n  \u003c/tags\u003e\n  \u003c!-- if you have any authentication: httpBasic info generation is implemented at the moment: \u003e\n  \u003ccomponents\u003e\n    \u003csecuritySchemes\u003e\n      \u003csecurityScheme name=\"httpBasic\"\u003e\n        This service uses HTTP Basic authentication.\n        \u003ctype\u003ehttp\u003c/type\u003e\n        \u003cscheme\u003ebasic\u003c/scheme\u003e\n      \u003c/securityScheme\u003e\n    \u003c/securitySchemes\u003e\n  \u003c/components\u003e\n  \u003csecurity\u003e\n    \u003cSecurityRequirement name=\"httpBasic\"/\u003e\n  \u003c/security\u003e \u003c!- --\u003e\n\u003c/config\u003e\n```\n\n* You can either put the contents of this repository in your RESTXQ directory and have the swagger-ui ready\n  and load `openapi.xqm` from `openapi4restxq/content/openapi.xqm`\n* or you copy `content/openapi.xqm`, `openapi-config.xml` and `spdx-licenses.json` for example into `3rd-party/openapi`.\n  These files represent the XQuery code and some default configuration needed.\n\nYou then add a invocation like this (adjust the `at \"3rd-party/content/openapi.xqm\"` if you don't copy `openapi.xqm`)\n\n```xq\nimport module namespace openapi=\"https://lab.sub.uni-goettingen.de/restxqopenapi\" at \"3rd-party/content/openapi.xqm\";\n[...]\ndeclare\n    %rest:path('/yourrestproject/openapi.json')\n    %rest:produces('application/json')\n    %output:media-type('application/json')\nfunction yourrestproject:getOpenapiJSON() as item()+ {\n  openapi:json(file:base-dir())\n};\n```\n\nThis makes a json representation of your annotated and documented API avaialable.\n\nYou can load this in swagger-ui if you type `/yourrestproject/openapi.json` into the default explore input box.\nIf you want to configure [swagger-ui's start parameters](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md) have a look at the documentation.\nFor example to have just a predefined set of openapi specifications available try the following code in `openapi4restxq/resources/swagger-ui-dist/index.html`:\n\n```javascript\n    window.onload = function() {\n      // Begin Swagger UI call region\n      const ui = SwaggerUIBundle({\n        urls: [\n          { url: \"/yourrestproject/openapi.json\", name: \"my rest API\"},\n          { url: \"https://petstore.swagger.io/v2/swagger.json\", name: \"petstore example API\"}\n        ],\n        dom_id: '#swagger-ui',\n        deepLinking: true,\n        presets: [\n          SwaggerUIBundle.presets.apis,\n          SwaggerUIStandalonePreset\n        ],\n        plugins: [\n          SwaggerUIBundle.plugins.DownloadUrl\n        ],\n        layout: \"StandaloneLayout\"\n      })\n      // End Swagger UI call region\n\n      window.ui = ui\n    }\n```\n\n### Standalone\n\nBy default the application provides a preview and a few simple REST paths as test\ninterfaces. Open the application via the Dashboard or browse to [http://localhost:8984/openapi/index.html](http://localhost:8984/openapi/index.html).\n\nChange the the input filed in the top bar to `openapi.json`.\n\nTo view the documentation for other packages, use the input filed in the top bar\nto ask for a description file at `openapi.json?target=Q:\\BaseX9\\webapp\\myApplication\\`.\n\n## Configure\n\nTo include information not present in one of the parsed documents, the library\nchecks the availability of a resources named `openapi-config.xml` in the\nroot collection of the application where to create the description file for.\nIt is recommended to place a customized copy of the file provided with this\npackage.\n\n## Develop\n\nTo start developing or testing the package just change `openapi.xqm`\n\nBehind the curtain the information will be collected by calling\n\n```xq\ninspect:module(\"/basex/webapp/yourproject/yourmodule.xqm\")\n```\n\nNote that `inspect:module` and its exist-db counterpart generate comapreable but\ndifferent XML.\n\n## Limitations\n\n### combining path and query parameters\n\nQuery parameters passed by `%rest:query-param()` MUST use a name different from\npath parameter variable names. Since the parameter name can be defined different\nfrom the variable name via this function, it is REQUIRED to use different path\nvariable name and query parameter names. It is CONSIDERED to be best practice\nthat both – name and var name – SHOULD not interfere or have any cross-realation\nby their names.\n\n### Example values\n\nExample values are taken from the `%test:arg()` annotation and the usage of\n`%test:args()` is not supported.\n\n## Credits\n\n* swagger.io for swagger-ui\n* Mathias Goebel for the [exist-db version of this tool](https://gitlab.gwdg.de/subugoe/openapi4restxq)\n\nThere is no relation between the author of this software and the named companies,\ninitiatives, products, specifications and trademarks.\n\nThis software is written to comply with the OpenAPI Specifications (OAS) and\nprovides an implementation for RESTXQ. It is tested with eXist-db eXclusively.\n\nUsage of the [OpenAPI Logo](icon.png) is in accordance to the guidelines\nprovided at [openapis.org/faq](https://www.openapis.org/faq). In this case it is\nused to appear on eXist-db dashboard screen when this application is installed.\n\nOAS and OpenAPI Specification and their respective logos, are trademarks of The\nLinux Foundation. Linux is a registered trademark of Linus Torvalds.\n\n# Thank You, Open Source!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facdh-oeaw%2Fopenapi4restxq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facdh-oeaw%2Fopenapi4restxq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facdh-oeaw%2Fopenapi4restxq/lists"}