Initial version

README.md

@@ -1,14 +1,14 @@
-# (project title)
+# Swagger
 
-(project description).
+Integrate Swagger into XWiki to enable the direct display of OpenAPI specifications.
 
-* Project Lead: [(name)](https://www.xwiki.org/xwiki/bin/view/XWiki/(profile id on xwiki.org))
-* Documentation & Downloads: [Documentation & Download](https://extensions.xwiki.org/xwiki/bin/view/Extension/(extension name)))
-* [Issue Tracker](https://jira.xwiki.org/browse/(jira id)
+* Project Lead: [Farcasi Alexandru](https://www.xwiki.org/xwiki/bin/view/XWiki/Farcasut)
+* Documentation & Downloads: [Documentation & Download](https://extensions.xwiki.org/xwiki/bin/view/Extension/(extension name))
+* [Issue Tracker](https://jira.xwiki.org/browse/https://jira.xwiki.org/projects/XSWAG/summary)
 * Communication: [Forum](https://forum.xwiki.org/), [Chat](https://dev.xwiki.org/xwiki/bin/view/Community/Chat)
 * [Development Practices](https://dev.xwiki.org)
-* Minimal XWiki version supported: XWiki (minimal xwiki version)
+* Minimal XWiki version supported: XWiki 14.10
 * License: LGPL 2.1
 * Translations: N/A
-* Sonar Dashboard: [![Status](https://sonarcloud.io/api/project_badges/measure?project=(group id):(artifact id)&metric=alert_status)](https://sonarcloud.io/dashboard?id=(group id):(artifact id))
-* Continuous Integration Status: [![Build Status](https://ci.xwiki.org/job/XWiki%20Contrib/job/(project id on ci)/job/master/badge/icon)](https://ci.xwiki.org/job/XWiki%20Contrib/job/(projct id on ci)/job/master/)
+* Sonar Dashboard: N/A
+* Continuous Integration Status: N/A

pom.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.xwiki.contrib</groupId>
+    <artifactId>parent-platform</artifactId>
+    <version>14.10-1</version>
+  </parent>
+  <groupId>org.xwiki.contrib.swagger</groupId>
+  <artifactId>swagger-parent</artifactId>
+  <packaging>pom</packaging>
+  <name>Swagger macro - Parent POM</name>
+  <version>1.0-SNAPSHOT</version>
+  <properties>
+    <xwiki.release.jira.skip>false</xwiki.release.jira.skip>
+    <!-- If the project is hosted on http://jira.xwiki.org, only the id needs to be provided. -->
+    <xwiki.issueManagement.jira.id>XSWAG</xwiki.issueManagement.jira.id>
+  </properties>
+  <developers>
+    <developer>
+      <name>Farcasi Alexandru</name>
+    </developer>
+  </developers>
+  <scm>
+    <connection>scm:git:git://github.com/xwiki-contrib/swagger.git</connection>
+    <developerConnection>scm:git:[email protected]:xwiki-contrib/swagger.git</developerConnection>
+    <url>https://github.com/xwiki-contrib/swagger/tree/master</url>
+    <tag>HEAD</tag>
+  </scm>
+  <modules>
+    <module>swagger-macro</module>
+    <module>swagger-api</module>
+  </modules>
+</project>

swagger-api/pom.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.xwiki.contrib.swagger</groupId>
+    <artifactId>swagger-parent</artifactId>
+    <version>1.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>swagger-api</artifactId>
+  <packaging>jar</packaging>
+  <name>Swagger API</name>
+  <version>1.0-SNAPSHOT</version>
+  <description>Swagger macro for displaying OpenAPI specifications.</description>
+  <dependencies>
+    <dependency>
+      <groupId>org.xwiki.commons</groupId>
+      <artifactId>xwiki-commons-component-api</artifactId>
+      <version>${commons.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.xwiki.commons</groupId>
+      <artifactId>xwiki-commons-script</artifactId>
+      <version>${commons.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.xwiki.commons</groupId>
+      <artifactId>xwiki-commons-extension-api</artifactId>
+      <version>${commons.version}</version>
+    </dependency>
+    <!-- Needed for http classes -->
+    <dependency>
+      <groupId>org.xwiki.platform</groupId>
+      <artifactId>xwiki-platform-configuration-default</artifactId>
+      <version>${platform.version}</version>
+    </dependency>
+    <!-- UriBuilder -->
+    <dependency>
+      <groupId>javax.ws.rs</groupId>
+      <artifactId>jsr311-api</artifactId>
+    </dependency>
+  </dependencies>
+</project>

swagger-api/src/main/java/org/xwiki/contrib/swagger/internal/HttpClientBuilderFactory.java

@@ -0,0 +1,49 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.contrib.swagger.internal;
+
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.impl.client.HttpClients;
+import org.xwiki.component.annotation.Component;
+import org.xwiki.stability.Unstable;
+
+import javax.inject.Singleton;
+
+/**
+ * Simple factory for creating a HttpClient to help testing.
+ *
+ * @version $Id$
+ * @since 1.0
+ */
+@Component(roles = HttpClientBuilderFactory.class)
+@Singleton
+@Unstable
+public class HttpClientBuilderFactory
+{
+    /**
+     * Creates a HttpClient.
+     *
+     * @return a new HttpClient
+     */
+    public CloseableHttpClient create()
+    {
+        return HttpClients.createDefault();
+    }
+}

swagger-api/src/main/java/org/xwiki/contrib/swagger/internal/Proxy.java

@@ -0,0 +1,160 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.contrib.swagger.internal;
+
+import java.io.IOException;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.util.Base64;
+
+import javax.inject.Inject;
+import javax.inject.Singleton;
+import javax.ws.rs.core.UriBuilder;
+
+import org.apache.http.client.methods.CloseableHttpResponse;
+import org.apache.http.client.methods.HttpGet;
+import org.apache.http.impl.client.CloseableHttpClient;
+import org.apache.http.util.EntityUtils;
+import org.slf4j.Logger;
+import org.xwiki.component.annotation.Component;
+import org.xwiki.stability.Unstable;
+
+/**
+ * Retrieves the OpenAPI specification from URL.
+ *
+ * @version $Id$
+ * @since 1.0
+ */
+@Component(roles = Proxy.class)
+@Singleton
+@Unstable
+public class Proxy
+{
+    /**
+     * Failsafe to make sure that we return a valid object even if the request fails.
+     */
+    private static final String DEFAULT_OBJECT = "{}";
+
+    private static final String AUTHORIZATION_HEADER = "Authorization";
+
+    @Inject
+    private Logger logger;
+
+    @Inject
+    private HttpClientBuilderFactory httpClientBuilderFactory;
+
+    /**
+     * Makes the request to retrieve the OpenAPI specification and returns it.
+     *
+     * @param url address from where to retrieve the OpenAPI specification
+     * @param accessToken authentication token for accessing the data
+     * @param username bitbucket username for accessing the resource.
+     * @param password bitbucket password for accessing the resouce
+     * @return OpenAPI specification as a string
+     * @throws IOException
+     * @throws URISyntaxException
+     */
+    public String request(String url, String accessToken, String username, String password)
+        throws IOException, URISyntaxException
+    {
+        if (url == null || url.isEmpty()) {
+            return DEFAULT_OBJECT;
+        }
+        // We are having 4 cases: random url, github, gitlab, bitbucket
+        URL basicURL = new URL(url);
+        if (basicURL.getHost().contains("github")) {
+            return handleGithub(basicURL, accessToken);
+        } else if (basicURL.getHost().contains("gitlab")) {
+            return handleGitlab(basicURL, accessToken);
+        } else if (basicURL.getHost().contains("bitbucket")) {
+            return handleBitbucket(basicURL, username, password);
+        } else {
+            return handleBasicURL(basicURL);
+        }
+    }
+
+    private String handleBasicURL(URL basicURL) throws IOException, URISyntaxException
+    {
+        try (CloseableHttpClient client = httpClientBuilderFactory.create()) {
+            return executeRequest(client, new HttpGet(basicURL.toURI()));
+        }
+    }
+
+    private String handleGithub(URL basicURL, String accessToken) throws IOException, URISyntaxException
+    {
+        try (CloseableHttpClient client = httpClientBuilderFactory.create()) {
+            HttpGet get = new HttpGet(basicURL.toURI());
+
+            // Add headers if accessToken is provided
+            if (accessToken != null && !accessToken.isEmpty()) {
+                get.addHeader(AUTHORIZATION_HEADER, String.format("Bearer %s", accessToken));
+            }
+            get.addHeader("Accept", "application/vnd.github.v3.raw");
+
+            return executeRequest(client, get);
+        }
+    }
+
+    private String executeRequest(CloseableHttpClient client, HttpGet get) throws IOException
+    {
+        try (CloseableHttpResponse response = client.execute(get)) {
+            // Return the response body if status code is 200
+            if (response.getStatusLine().getStatusCode() == 200) {
+                return EntityUtils.toString(response.getEntity());
+            } else {
+                int statusCode = response.getStatusLine().getStatusCode();
+                logger.error("Request failed with status code: {[]}", statusCode);
+            }
+        } catch (IOException e) {
+            // Log any exception that occurs during the request execution
+            logger.error("Exception occurred while executing the request: {[]}", e.getMessage(), e);
+        }
+
+        // Failsafe: return an empty JSON object if status code is not 200
+        return DEFAULT_OBJECT;
+    }
+
+    private String handleBitbucket(URL basicURL, String username, String password)
+        throws IOException, URISyntaxException
+    {
+        try (CloseableHttpClient client = httpClientBuilderFactory.create()) {
+            HttpGet get = new HttpGet(basicURL.toURI());
+            if (username != null && password != null && !username.isEmpty() && !password.isEmpty()) {
+                String preEncode = String.format("%s:%s", username, password);
+                get.addHeader(AUTHORIZATION_HEADER, String.format("Basic %s",
+                    Base64.getEncoder().encodeToString(preEncode.getBytes())));
+            }
+            return executeRequest(client, get);
+        }
+    }
+
+    private String handleGitlab(URL basicURL, String accessToken) throws URISyntaxException, IOException
+    {
+        try (CloseableHttpClient client = httpClientBuilderFactory.create()) {
+            if (accessToken != null && !accessToken.isEmpty()) {
+                // Gitlab uses the token in the qParams
+                UriBuilder builder = UriBuilder.fromUri(basicURL.toURI());
+                builder.queryParam("private_token", accessToken);
+                return executeRequest(client, new HttpGet(builder.build()));
+            }
+            return executeRequest(client, new HttpGet(basicURL.toURI()));
+        }
+    }
+}

swagger-api/src/main/java/org/xwiki/contrib/swagger/internal/pickers/Expansion.java

@@ -0,0 +1,42 @@
+/*
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+package org.xwiki.contrib.swagger.internal.pickers;
+
+/**
+ * Picker for the expansion parameter of thw swagger macro.
+ *
+ * @version $Id$
+ * @since 1.0
+ */
+public enum Expansion
+{
+    /**
+     * The methods and tags are fully collapsed.
+     */
+    none,
+    /**
+     * Only the tags are expanded.
+     */
+    list,
+    /**
+     * Both the tags and the HTTP methods are expanded.
+     */
+    full
+}