From 12ecfa88cd637ecc990ca9631399edd249721994 Mon Sep 17 00:00:00 2001
From: Harikrishna <harikrishna.patnala@gmail.com>
Date: Wed, 13 Jul 2022 15:34:46 +0530
Subject: [PATCH] Added deprecated API indication in the API doc (#6545)

* Added deprecated command indication as (D) in the API doc

* Fixed line allignment
---
 .../src/main/java/com/cloud/api/doc/ApiXmlDocWriter.java | 4 +++-
 server/src/main/java/com/cloud/api/doc/Command.java      | 9 +++++++++
 tools/apidoc/gen_toc.py                                  | 5 ++++-
 tools/apidoc/generatetoc_header.xsl                      | 1 +
 4 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/server/src/main/java/com/cloud/api/doc/ApiXmlDocWriter.java b/server/src/main/java/com/cloud/api/doc/ApiXmlDocWriter.java
index 916c78f650e..d4beb247709 100644
--- a/server/src/main/java/com/cloud/api/doc/ApiXmlDocWriter.java
+++ b/server/src/main/java/com/cloud/api/doc/ApiXmlDocWriter.java
@@ -214,9 +214,11 @@ public class ApiXmlDocWriter {
             }
 
             boolean isAsync = ReflectUtil.isCmdClassAsync(clas, new Class<?>[] {BaseAsyncCmd.class, BaseAsyncCreateCmd.class});
-
             apiCommand.setAsync(isAsync);
 
+            boolean isDeprecated = clas.getAnnotation(Deprecated.class) != null;
+            apiCommand.setDeprecated(isDeprecated);
+
             Set<Field> fields = ReflectUtil.getAllFieldsForClass(clas, new Class<?>[] {BaseCmd.class, BaseAsyncCmd.class, BaseAsyncCreateCmd.class});
 
             request = setRequestFields(fields);
diff --git a/server/src/main/java/com/cloud/api/doc/Command.java b/server/src/main/java/com/cloud/api/doc/Command.java
index 549ca291ffe..8d08a51a6e4 100644
--- a/server/src/main/java/com/cloud/api/doc/Command.java
+++ b/server/src/main/java/com/cloud/api/doc/Command.java
@@ -32,6 +32,7 @@ public class Command implements Serializable{
     private String sinceVersion = null;
     private ArrayList<Argument> request;
     private ArrayList<Argument> response;
+    private boolean isDeprecated;
 
     public Command(String name, String description) {
         this.name = name;
@@ -114,4 +115,12 @@ public class Command implements Serializable{
     public void setUsage(String usage) {
         this.usage = usage;
     }
+
+    public boolean isDeprecated() {
+        return isDeprecated;
+    }
+
+    public void setDeprecated(boolean deprecated) {
+        isDeprecated = deprecated;
+    }
 }
diff --git a/tools/apidoc/gen_toc.py b/tools/apidoc/gen_toc.py
index 18996028182..77dd56268c0 100644
--- a/tools/apidoc/gen_toc.py
+++ b/tools/apidoc/gen_toc.py
@@ -234,6 +234,7 @@ for f in sys.argv:
             dom = minidom.parse(data)
         name = dom.getElementsByTagName('name')[0].firstChild.data
         isAsync = dom.getElementsByTagName('isAsync')[0].firstChild.data
+        isDeprecated = dom.getElementsByTagName('isDeprecated')[0].firstChild.data
         category = choose_category(fn)
         if category not in categories:
             categories[category] = []
@@ -241,6 +242,7 @@ for f in sys.argv:
             'name': name,
             'dirname': dirname_to_dirname[dirname],
             'async': isAsync == 'true',
+            'deprecated': isDeprecated == 'true',
             'user': dirname_to_user[dirname],
             })
     except ExpatError as e:
@@ -252,9 +254,10 @@ for f in sys.argv:
 def xml_for(command):
     name = command['name']
     isAsync = command['async'] and ' (A)' or ''
+    isDeprecated = command['deprecated'] and ' (D)' or ''
     dirname = command['dirname']
     return '''<xsl:if test="name=\'%(name)s\'">
-<li><a href="%(dirname)s/%(name)s.html"><xsl:value-of select="name"/>%(isAsync)s</a></li>
+<li><a href="%(dirname)s/%(name)s.html"><xsl:value-of select="name"/>%(isAsync)s %(isDeprecated)s</a></li>
 </xsl:if>
 ''' % locals()
 
diff --git a/tools/apidoc/generatetoc_header.xsl b/tools/apidoc/generatetoc_header.xsl
index 4feb10eff3a..5b882641f3b 100644
--- a/tools/apidoc/generatetoc_header.xsl
+++ b/tools/apidoc/generatetoc_header.xsl
@@ -66,5 +66,6 @@ version="1.0">
                                 <span>Commands available through the developer API URL and the integration API URL.</span>
                                 <div class="api_legends">
            				<p><span class="api_legends_async">(A)</span> implies that the command is asynchronous.</p>
+                                        <p><span class="api_legends_async">(D)</span> implies that the command is deprecated.</p>
 					<p>(*) implies element has a child.</p>
  				</div>