Is there a Swagger/OpenAPI Documentation for FarmOS HTTP methods with its Record types that can be found in my self-hosted application or in another site?
There are some Drupal contrib modules that you can install which provide this, but it might take some experimentation to get it all set up right. I tried it a while ago and I think it worked. The additional overhead and extra dependencies were not worth including in farmOS core, so we decided to just leave it up to self-hosting site admins to experiment with if they wanted to.
Alternatively, you can get all the information you need already in JSON format at the
/api has links to all the available data endpoints, and
/api/schema has links to all the JSON Schema descriptions of each data type.
farmOS uses the Drupal core JSON:API module and the contib JSON:API Schema module to provide all of these things for us automatically. We didn’t have to build any of it.
JSON:API is a standard that is not Drupal specific. See https://jsonapi.org/ for more information.
Drupal.org also has some good docs about how to use JSON:API generally:
We have some basic docs for farmOS specifically, which mainly provides links to these other resources, but would be great to expand more: API | farmOS
I already installed OpenAPI UI in my hosted site but I don’t know how to make it appear in my hosted site. Do I need to install all the mentioned libraries of OpenAPI in your comment or just one of them? Hopefully I can figure out how to make it appear as a page on my self-hosted FarmOS app but not having luck right now. Youtube doesn’t have videos that show what to do after installing Drupal’s OpenAPI libraries
Probably you know which page to visit after installing some or all OpenAPI Libraries to see the generated OpenAPI docs.
I know how to setup Swagger in Java/Spring Boot but not so much in Drupal. My understanding is that Drupal is a PHP framework.
It’s been a while since I’ve tried this, so I don’t remember the exact steps. I know you need all of the modules I linked to above, as well as any associated PHP libraries required by the modules via Composer.
I would suggest joining the Drupal Slack: Slack | Drupal.org
You can find more general Drupal support there. If you take the time to figure this out, please report your results back here to benefit others in the future!
Ok will see what information I can gather there, try it on my own app and let you know what the results are.
Would love to hear you find out - I think have nice swagger docs on each instance would be fantastic!
Finally figured out how to get the Swagger definition!!
1. First to install the following modules in the self-hosted FarmOS module page:
2. Go to each drupal page of each module listed in the filtered modules
3. Copy either link inside the shape. Personally I copied the tar.gz link
4. Click Add New Module
5. Paste the link to “Add from a URL”
6. Click continue
7. From here keep following the steps. After successfully adding modules you should enable/install the modules on the first photo by going back to Extend page
8. Please also add the modules needed by those modules
9. After success in all steps you should be able to see these:
Also if you want to import the swagger file to Postman or SwaggerHub, it can also be done. Just copy the entire text in the picture before this last photo and save it as json
This link is also helpful
Thanks for sharing your findings @farm!!
In my opinion these modules shouldn’t be included in farmOS core (for simplicity, security, avoiding upgrade hurdles, etc), but they could certainly be installed by anyone hosting farmOS. In practice, I feel like they are only really useful during development, though, and afterwards (once you have built something that uses the API) they are no longer necessary. So, if it were me, I would only install these in a local environment, do my dev/testing against that, and omit them from production deployments.