From dc41839c801d11f2dfc93a37494bf18a3e1b2a46 Mon Sep 17 00:00:00 2001
From: Petri Lehtinen <petri@digip.org>
Date: Wed, 16 Mar 2022 21:46:46 +0200
Subject: [PATCH] Add upgrading instructions

---
 README.md         |  2 ++
 docs/upgrading.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 docs/upgrading.md

diff --git a/README.md b/README.md
index 5ea65753..28a4d6c4 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,8 @@
 `typera-openapi` is an tool that automatically creates [OpenAPI v3] definitions
 for projects that use [typera] for routes.
 
+Upgrading to v2? See the [upgrading instructions](docs/upgrading.md).
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
diff --git a/docs/upgrading.md b/docs/upgrading.md
new file mode 100644
index 00000000..ae96e048
--- /dev/null
+++ b/docs/upgrading.md
@@ -0,0 +1,82 @@
+# Upgrading from v1 to v2
+
+In v1, typera-openapi generated one file per source file. In v2, all the OpenAPI
+stuff is put to a single file.
+
+Why? Because starting from v2, typera-openapi generates the schemas from
+`interface` and `type` alias object types under `components` and uses
+`"$ref": "#/components/schemas/TypeName"`. This results in a more concise
+output, sometimes more readable API documentation for the end user, and supports
+types that are defined recursively (i.e. reference themselves directly or
+indirectly).
+
+## Upgrading the CLI options
+
+_Use the `-o`/`--outfile` option to write to a specific file._ The default is
+`openapi.ts` in the working directory.
+
+Old:
+
+```
+$ typera-openapi src/routes1.ts src/routes2.ts
+```
+
+New:
+
+```
+$ typera-openapi -o src/openapi.ts src/routes1.ts src/routes2.ts
+```
+
+_Remove the `--format` option._ The output format is selected by the output file
+suffix. `.ts` writes TypeScript, `.json` writes JSON.
+
+Old:
+
+```
+$ typera-openapi --format json src/routes1.ts src/routes2.ts
+```
+
+New:
+
+```
+$ typera-openapi -o src/openapi.json src/routes1.ts src/routes2.ts
+```
+
+## Upgrading your code
+
+Because the output is in a single file, there's no need to merge paths objects
+anymore.
+
+Old:
+
+```
+import routeDefs from './routes.openapi'
+import otherDefs from './others.openapi'
+
+const openapiDoc: OpenAPIV3.Document = {
+  openapi: '3.0.0',
+  info: {
+    title: 'My cool API',
+    version: '0.1.0',
+  },
+  paths: {
+    ...routeDefs.paths,
+    ...otherDefs.paths
+  }
+}
+```
+
+New:
+
+```
+import openapi from './openapi'
+
+const openapiDoc: OpenAPIV3.Document = {
+  openapi: '3.0.0',
+  info: {
+    title: 'My cool API',
+    version: '0.1.0',
+  },
+  ...openapi,
+}
+```