From 3d232c87f4bb399545f0f948bc8f6210661f80c4 Mon Sep 17 00:00:00 2001
From: Gergo Torcsvari <torcsvari.gergo@gmail.com>
Date: Sun, 6 Dec 2020 13:34:34 +0100
Subject: [PATCH] sbt-openapi-codegen; documentation

---
 doc/Makefile                         |  2 +-
 doc/conf.py                          |  6 ++-
 doc/generator/sbt-openapi-codegen.md | 62 ++++++++++++++++++++++++++++
 doc/index.md                         |  6 +++
 doc/requirements.pip                 |  3 +-
 5 files changed, 75 insertions(+), 4 deletions(-)
 create mode 100644 doc/generator/sbt-openapi-codegen.md

diff --git a/doc/Makefile b/doc/Makefile
index 94b51a0240..3eda9474b0 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/doc/conf.py b/doc/conf.py
index 916c6f95b5..829faf9baa 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -30,7 +30,9 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx_markdown_tables',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -182,4 +184,4 @@ def setup(app):
         'auto_toc_tree_section': 'Contents',
         'enable_auto_doc_ref': False
     }, True)
-    app.add_transform(AutoStructify)
\ No newline at end of file
+    app.add_transform(AutoStructify)
diff --git a/doc/generator/sbt-openapi-codegen.md b/doc/generator/sbt-openapi-codegen.md
new file mode 100644
index 0000000000..20e578c4e1
--- /dev/null
+++ b/doc/generator/sbt-openapi-codegen.md
@@ -0,0 +1,62 @@
+# Generate endpoint definitions from an OpenAPI YAML
+
+```eval_rst
+.. note::
+
+  This is a really early alpha implementation.
+```
+
+## Installation steps
+
+Add the sbt plugin to the `project/plugins.sbt`:
+
+```scala
+addSbtPlugin("com.softwaremill.sttp.tapir" % "sbt-openapi-codegen" % "@VERSION@")
+```
+
+Enable the plugin for your project in the `build.sbt`:
+
+```scala
+enablePlugins(OpenapiCodegenPlugin)
+```
+
+Add your OpenApi file to the project, and override the `openapiSwaggerFile` setting in the `build.sbt`:
+
+```scala
+openapiSwaggerFile := baseDirectory.value / "swagger.yaml"
+```
+
+At this point your compile step will try to generate the endpoint definitions 
+to the `sttp.tapir.generated.TapirGeneratedEndpoints` object, where you can access the 
+defined case-classes and endpoint definitions.
+
+## Usage and options
+
+The generator currently supports these settings, you can override them in the `build.sbt`;
+
+| setting | default value | description |
+|---|---|---|
+| openapiSwaggerFile | baseDirectory.value / "swagger.yaml" | The swagger file with the api definitions. |
+| openapiPackage | sttp.tapir.generated | The name for the generated package. |
+| openapiObject | TapirGeneratedEndpoints | The name for the generated object. |
+
+The general usage is;
+
+```scala
+import sttp.tapir.generated._
+import sttp.tapir.docs.openapi._
+import sttp.tapir.openapi.circe.yaml._
+
+val docs = TapirGeneratedEndpoints.generatedEndpoints.toOpenAPI("My Bookshop", "1.0")
+```
+
+### Limitations
+
+Currently, the generated code depends on `"io.circe" %% "circe-generic"`. In the future probably we will make the encoder/decoder json lib configurable (PRs welcome).
+
+We currently miss a lot of OpenApi features like:
+ - tags
+ - enums/ADTs
+ - missing model types and meta descriptions (like date, minLength)
+ - file handling
+
diff --git a/doc/index.md b/doc/index.md
index f04d49b6bc..d102314304 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -158,6 +158,12 @@ Development and maintenance of sttp tapir is sponsored by [SoftwareMill](https:/
 
    testing
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Generators
+   
+   generator/sbt-openapi-codegen
+   
 .. toctree::
    :maxdepth: 2
    :caption: Other subjects
diff --git a/doc/requirements.pip b/doc/requirements.pip
index 14c7601b41..55f8b74e68 100644
--- a/doc/requirements.pip
+++ b/doc/requirements.pip
@@ -1,4 +1,5 @@
 sphinx_rtd_theme==0.4.3
 recommonmark==0.5.0
 sphinx==2.0.1
-sphinx-autobuild==0.7.1
\ No newline at end of file
+sphinx-autobuild==0.7.1
+sphinx-markdown-tables==0.0.15