Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[PoC] Add docusaurus-openapi-docs #82

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

[PoC] Add docusaurus-openapi-docs #82

wants to merge 2 commits into from

Conversation

HLeithner
Copy link
Member

@HLeithner HLeithner commented Jan 28, 2023

@HLeithner
Copy link
Member Author

@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
Copy link
Contributor

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

@alexandreelise
Copy link
Contributor

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
Copy link
Member Author

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
Copy link
Contributor

alexandreelise commented Sep 20, 2023

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
Copy link
Contributor

like openapi docu could be part of the extension it self

By extension you mean a joomla extension ? @HLeithner

@HLeithner
Copy link
Member Author

like openapi docu could be part of the extension it self

By extension you mean a joomla extension ? @HLeithner

Yes

@alexandreelise
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Contributor

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.

@HLeithner
Copy link
Member Author

Updated pull request, but needed to disable the search because of an error...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants