diff --git a/.gitignore b/.gitignore
index 13d120d95267..b79ef1dd8443 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,5 +23,6 @@ tags
 .Gopkg.*
 .GeneratedDockerfile
 .gradle
-*.adoc
-html5
+hack/gen-swagger-doc/*.adoc
+hack/gen-swagger-doc/*.md
+hack/gen-swagger-doc/html5
diff --git a/hack/gen-swagger-doc/build.gradle b/hack/gen-swagger-doc/build.gradle
index 2a488ddcde91..dfecf7aa1774 100644
--- a/hack/gen-swagger-doc/build.gradle
+++ b/hack/gen-swagger-doc/build.gradle
@@ -5,25 +5,29 @@ buildscript {
     }
 
     dependencies {
-        classpath "io.github.swagger2markup:swagger2markup:1.3.1"
+        classpath "io.github.swagger2markup:swagger2markup-gradle-plugin:1.3.1"
         classpath "org.asciidoctor:asciidoctor-gradle-plugin:1.5.6"
     }
 }
 
-apply plugin: 'org.asciidoctor.convert'
+apply plugin: 'io.github.swagger2markup'
 
-task gendocs << {
-  io.github.swagger2markup.Swagger2MarkupConverter
-    .from(java.nio.file.Paths.get("./api/openapi-spec/swagger.json"))
-    .build()
-    .toFolder(java.nio.file.Paths.get("./hack/gen-swagger-doc"));
+convertSwagger2markup {
+    swaggerInput "./api/openapi-spec/swagger.json"
+    outputDir file("./")
+    config = [
+        'swagger2markup.markupLanguage': markupLanguage,
+        'swagger2markup.interDocumentCrossReferencesEnabled': true,
+    ]
 }
 
+apply plugin: 'org.asciidoctor.convert'
+
 asciidoctor {
   sourceDir = file('./')
   sources {
     // paths.adoc is being renamed to operations.adoc by gen-swagger-docs.sh.
-    // Keeping it here in case somebody run: gradle gendocs asciidoctor
+    // Keeping it here in case somebody run: gradle convertSwagger2markup asciidoctor
     include 'definitions.adoc', 'overview.adoc', 'paths.adoc',  'security.adoc', 'operations.adoc'
   }
   outputDir = file('./')
diff --git a/hack/gen-swagger-doc/gen-swagger-docs.sh b/hack/gen-swagger-doc/gen-swagger-docs.sh
index 020d83f12097..0bffa395b9c1 100755
--- a/hack/gen-swagger-doc/gen-swagger-docs.sh
+++ b/hack/gen-swagger-doc/gen-swagger-docs.sh
@@ -1,53 +1,88 @@
 #!/bin/bash
 
+# gen-swagger-docs.sh $API_VERSION $OUTPUT_FORMAT
+# API_VERSION=v1
+# OUTPUT_FORMAT=html|markdown
+
 set -o errexit
 set -o nounset
 set -o pipefail
 
 VERSION="${1:-v1}"
+OUTPUT_FORMAT="${2:-html}"
+if [ "$OUTPUT_FORMAT" = "html" ] ;
+then
+    SUFFIX="adoc"
+    HEADER="="
+    LINK1_TEMPLATE="\* \<\<\${VERSION}.\$m\>\>"
+    LINK_DEFINITIONS="* link:./definitions.html[Types Definition]"
+    LINK_OPERATIONS="* link:./operations.html[Operations]"
+    GRADLE_EXTRA_PARAMS=""
+elif [ "$OUTPUT_FORMAT" = "markdown" ] ;
+then
+    SUFFIX="md"
+    HEADER="#"
+    LINK1_TEMPLATE="\* [\${VERSION}.\$m]\(definitions.md#\${VERSION}-\${m,,}\)"
+    LINK_DEFINITIONS="* [Types Definition](definitions.md)"
+    LINK_OPERATIONS="* [Operations](operations.md)"
+    GRADLE_EXTRA_PARAMS="-PmarkupLanguage=MARKDOWN"
+else
+    echo "Unknown OUTPUT_FORMAT=${OUTPUT_FORMAT}"
+    exit 1
+fi
 WORKDIR="hack/gen-swagger-doc"
 GRADLE_BUILD_FILE="$WORKDIR/build.gradle"
 
+
 # Generate *.adoc files from swagger.json
-gradle -b $GRADLE_BUILD_FILE gendocs --info
+gradle -b $GRADLE_BUILD_FILE $GRADLE_EXTRA_PARAMS convertSwagger2markup --info
 
 #insert a TOC for top level API objects
-buf="== Top Level API Objects\n\n"
+buf="${HEADER}${HEADER} Top Level API Objects\n\n"
 top_level_models=$(grep '&[A-Za-z]*{},' pkg/api/${VERSION}/types.go | sed 's/.*&//;s/{},//')
 
-# check if the top level models exist in the definitions.adoc. If they exist,
+# check if the top level models exist in the definitions.$SUFFIX. If they exist,
 # their name will be <version>.<model_name>
 for m in $top_level_models
 do
-  if grep -xq "=== ${VERSION}.$m" "$WORKDIR/definitions.adoc"
+  if grep -xq "${HEADER}${HEADER}${HEADER} ${VERSION}.$m" "$WORKDIR/definitions.${SUFFIX}"
   then
-    buf+="* <<${VERSION}.$m>>\n"
+    buf+="$(eval echo $LINK1_TEMPLATE)\n"
   fi
 done
-sed -i "1i $buf" "$WORKDIR/definitions.adoc"
-
-# fix the links in .adoc, replace <<x,y>> with link:definitions.html#_x[y], and lowercase the _x part
-sed -i -e 's|<<\(.*\),\(.*\)>>|link:#\L\1\E[\2]|g' "$WORKDIR/definitions.adoc"
-sed -i -e 's|<<\(.*\),\(.*\)>>|link:./definitions.html#\L\1\E[\2]|g' "$WORKDIR/paths.adoc"
+sed -i "1i $buf" "$WORKDIR/definitions.${SUFFIX}"
 
 # change the title of paths.adoc from "paths" to "operations"
-sed -i 's|== Paths|== Operations|g' "$WORKDIR/paths.adoc"
-mv -f "$WORKDIR/paths.adoc" "$WORKDIR/operations.adoc"
+sed -i "s|${HEADER}${HEADER} Paths|${HEADER}${HEADER} Operations|g" "$WORKDIR/paths.${SUFFIX}"
+mv -f "$WORKDIR/paths.${SUFFIX}" "$WORKDIR/operations.${SUFFIX}"
 
 # $$ has special meaning in asciidoc, we need to escape it
-sed -i 's|\$\$|+++$$+++|g' "$WORKDIR/definitions.adoc"
+# TODO !!!
+#sed -i 's|\$\$|+++$$+++|g' "$WORKDIR/definitions.adoc"
 
 # Add links to definitons & operations under overview
-cat >> "$WORKDIR/overview.adoc" << __END__
-== KubeVirt API Reference
-[%hardbreaks]
-* link:./definitions.html[Types Definition]
-* link:./operations.html[Operations]
+cat >> "$WORKDIR/overview.${SUFFIX}" << __END__
+${HEADER}${HEADER} KubeVirt API Reference
 
+${LINK_DEFINITIONS}
+${LINK_OPERATIONS}
 __END__
 
 
-# Generate *.html files from *.adoc
-gradle -b $GRADLE_BUILD_FILE asciidoctor --info
+if [ "$OUTPUT_FORMAT" = "html" ] ;
+then
+  # Generate *.html files from *.adoc
+  gradle -b $GRADLE_BUILD_FILE asciidoctor --info
+elif [ "$OUTPUT_FORMAT" = "markdown" ] ;
+then
+    # Generate TOC for definitions & operations as README.md
+    cd "$WORKDIR"
+    echo "# KubeVirt API Reference" > README.md
+    curl \
+        https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc | \
+        bash -s "definitions.md" "operations.md" | \
+        sed 's/^      //' >> "README.md"
+    cd -
+fi
 
 echo "SUCCESS"
diff --git a/hack/gen-swagger-doc/gradle.properties b/hack/gen-swagger-doc/gradle.properties
new file mode 100644
index 000000000000..284894e36d1a
--- /dev/null
+++ b/hack/gen-swagger-doc/gradle.properties
@@ -0,0 +1 @@
+markupLanguage=ASCIIDOC