[PoC] Add docusaurus-openapi-docs

[HLeithner]

This is a proof of concept for openapi direct integration into docusaurus.

http://pr-82.manual.joomlacode.org/docs/using-core-functions/webservices/joomla-4-web-services-api-collection-for-postman

[HLeithner]

@carlitorweb and @alexandreelise

I created a proof of concept for the openapi implementation, the basis yaml provided by alex is a bit broken and also not really useful or at least there need to be done a big cleanup of the autogenerated stuff.

[alexandreelise]

@HLeithner you are right it's autogenerated and need more work, thanks for your feedback anyway

[alexandreelise]

Hi @HLeithner do you plan to use multi-file for openapi ?
For example split single openapi.yml to multiple files and using references and components section of openapi file for schemas of Banners,Articles,Contacts,Users,etc...
see OpenAPI 3.0.3 Spec

Here is what I have in mind and would have your thoughts about:

1. Banners
     banners.yaml
     clients.yaml
     categories.yaml
     1.4 Banners Content History
        keep.yaml
        contenthistory.yaml

...

openapi.yaml

Same directory structure than endpoints for multi-file Joomla Web Services openapi specification. And the openapi.yaml at the root level of the directory structure as the "entrypoint"

I made a work in progress tool to automate this task not in order not to do this manually.
Not implemented multi-file yet nor single file generation. Wanted your feedback first @carlitorweb @HLeithner

[HLeithner]

I'm open for anything, multiple files seems to make sense for me too.

In the long run I would like (or thinking of) to have parts of documentation in the main joomla repo, things like openapi docu could be part of the extension it self and be automatically updated if extension changes and pushed here.

I would also see this possible for the help documentation (backend per screen).

if you can do a PoC that would be really great.

[alexandreelise]

I'm open for anything, multiple files seems to make sense for me too.

In the long run I would like (or thinking of) to have parts of documentation in the main joomla repo, things like openapi docu could be part of the extension it self and be automatically updated if extension changes and pushed here.

I would also see this possible for the help documentation (backend per screen).

if you can do a PoC that would be really great.

I'll do my best. Helping other Super Joomlers when I can grok and grasp what Joomla Web Services can do and make open source tools to ease the adoption as much as I can. Happy to help. Good work you've done and other Joomla contributors and core team members. Keep up all of you Super Joomlers! Have a delightful day @HLeithner

[alexandreelise]

like openapi docu could be part of the extension it self

By extension you mean a joomla extension ? @HLeithner

[HLeithner]

like openapi docu could be part of the extension it self

By extension you mean a joomla extension ? @HLeithner

Yes

[alexandreelise]

like openapi docu could be part of the extension it self

By extension you mean a joomla extension ? @HLeithner

Yes

This would be for which version of Joomla?

[alexandreelise]

I did some homework and found this link about help servers

Do you mean to contribute on com_help to synchronize all help related to Web Services from always up-to-date openapi spec on each push to main branch of joomla/Manual? Dit I understood correctly @HLeithner ?

[HLeithner]

like openapi docu could be part of the extension it self

By extension you mean a joomla extension ? @HLeithner

Yes

This would be for which version of Joomla?

at this time it's only a idea could be 5.1 or 6.1, depending if other maintainer like the idea or not and if someone starts to work on it.

if we have the openapi spec definition in the media folder for the component for example it can be automatically used for the right version by 3rd party software also from public folders.

But for now having it in manual (automatically or not) would be a good starting point.

[HLeithner]

I did some homework and found this link about help servers

Do you mean to contribute on com_help to synchronize all help related to Web Services from always up-to-date openapi spec on each push to main branch of joomla/Manual? Dit I understood correctly @HLeithner ?

com_help is for help pages and maybe could do the same as the idea of having openapi specs in the cms.

for example the docs could also be part of the media folder having a markdown file per backend view.

Also something that could happen in the future or maybe not depending of other maintainers opinion.

[alexandreelise]

I did some homework and found this link about help servers
Do you mean to contribute on com_help to synchronize all help related to Web Services from always up-to-date openapi spec on each push to main branch of joomla/Manual? Dit I understood correctly @HLeithner ?

com_help is for help pages and maybe could do the same as the idea of having openapi specs in the cms.

for example the docs could also be part of the media folder having a markdown file per backend view.

Also something that could happen in the future or maybe not depending of other maintainers opinion.

I see. Indeed in the media folder it makes sense. media/com_openapi/docs/openapi.yml might possibly be indexed with smart search too as samrt search can index any mime types such as text/yaml.