(Auto)generate documentation

[guusdk]

The documentation that's provided with this plugin seems to be generated from the code. We should document how this is done. Ideally, it's automatically re-generated when the plugin is build (mvn clean package).

[ruicaramalho]

Hi what's the URL to get the Swagger Documentation?

[Fishbowler]

Based on the AuthFilter, looks to be at /plugins/restapi/v1/openapi.yaml

[ruicaramalho]

Im missing something.. If I try to open it in the browser it will treat .yaml as a file and download it.

PS -It does work if I open the index file:///C:/Program%20Files/Openfire/plugins/restapi/web/docs/index.html

[Fishbowler]

You're right.

I've just had a quick test on my local docker environment. After installation, there's a link in the settings. That links to /plugins/restapi/docs/index.html which opens the view you're looking for.

[ruicaramalho]

Thanks @Fishbowler .

The only thing that could be improved is that the swagger URL by default is `http://localhost:9090/plugins/restapi/v1/openapi.yaml'

It should have gotten the current location and port, in Javascript window.location.origin in my case:

[GregDThomas]

FWIW, a relative URL may well work, e.g. /plugins/restapi/v1/openapi.yaml (or even ../v1/openapi.yaml) (not tried either - but based on experience in other Swagger APIs

[ruicaramalho]

Thanks @GregDThomas but it does not work, it suggests downloading the file

[Fishbowler]

The only thing that could be improved is that the swagger URL by default is `http://localhost:9090/plugins/restapi/v1/openapi.yaml'

The location linked to from the settings page?

If so, I'll raise an issue.

(btw, you blanked your domain from the address bar, but not from your image, but these posts are editable if you care about keeping it unknown)

[ruicaramalho]

Solution:

Edit the index file and change to:

.......
<script>
    window.onload = function() {
        // Begin Swagger UI call region
        const ui = SwaggerUIBundle({
            url: window.location.origin+"/plugins/restapi/v1/openapi.yaml",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset
            ],
            plugins: [
                SwaggerUIBundle.plugins.DownloadUrl
            ],
            layout: "StandaloneLayout"
        });
        // End Swagger UI call region

        window.ui = ui;
    };
</script>
......

Originaly it was:

........
<script>
    window.onload = function() {
        // Begin Swagger UI call region
        const ui = SwaggerUIBundle({
            url: "http://localhost:9090/plugins/restapi/v1/openapi.yaml",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [
                SwaggerUIBundle.presets.apis,
                SwaggerUIStandalonePreset
            ],
            plugins: [
                SwaggerUIBundle.plugins.DownloadUrl
            ],
            layout: "StandaloneLayout"
        });
        // End Swagger UI call region

        window.ui = ui;
    };
</script>
........

[Fishbowler]

Ah yep. Got it.

https://github.com/igniterealtime/openfire-restAPI-plugin/blob/dfaa49ffa928ee641aca636c2911dcd9be722468/src/web/docs/index.html#L44

[ruicaramalho]

Thanks... it's fixed then :)

[ruicaramalho]

Hi Does this means, that this feature will be corrected in future versions?

PS -Sorry but I don't know how the GitHub works.

[ruicaramalho]

Hi @guusdk.

what I mean is if the index.html is going to be corrected. https://github.com/igniterealtime/openfire-restAPI-plugin/blob/dfaa49ffa928ee641aca636c2911dcd9be722468/src/web/docs/index.html#L44

To: url: window.location.origin+"/plugins/restapi/v1/openapi.yaml",