sbt-openapi-codegen; documentation

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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

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)
+    app.add_transform(AutoStructify)

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
+

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

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
+sphinx-autobuild==0.7.1
+sphinx-markdown-tables==0.0.15