From 692afd42a25ed422b4acf78d95ca46dd0122aeb1 Mon Sep 17 00:00:00 2001
From: Anastasiia Smirnova <asmirnova@playtika.com>
Date: Fri, 3 Jan 2020 11:41:55 +0200
Subject: [PATCH] Add initial version of `Migrating from SpringFox Swagger 2`
 doc

---
 docs/migrating-from-springfox.md | 79 ++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 docs/migrating-from-springfox.md

diff --git a/docs/migrating-from-springfox.md b/docs/migrating-from-springfox.md
new file mode 100644
index 00000000..14847121
--- /dev/null
+++ b/docs/migrating-from-springfox.md
@@ -0,0 +1,79 @@
+# Migrating from SpringFox Swagger 2
+
++ Remove springfox and swagger 2 dependencies. Add `springdoc-openapi-ui` dependency instead.
++ Replace swagger 2 annotations with swagger 3 annotations (it is already included with `springdoc-openapi-ui` dependency).
+Package for swagger 3 annotations is `io.swagger.v3.oas.annotations`.
+
+  - `@ApiParam` -> `@Parameter`
+  - `@ApiOperation` -> `@Operation`
+  - `@Api` -> `@Tag`
+  - `@ApiImplicitParams` -> `@Parameters`
+  - `@ApiImplicitParam` -> `@Parameter`
+  - `@ApiIgnore` -> `@Parameter(hidden = true)` or `@Operation(hidden = true)` or `@Hidden`
+  - `@ApiModel` -> `@Schema` 
+  - `@ApiModelProperty` -> `@Schema` 
+  
+
++ If you have **multiple** `Docket` beans replace them with `GroupedOpenApi` beans.
+
+  Before:
+  ```java
+      @Bean
+      public Docket publicApi() {
+          return new Docket(DocumentationType.SWAGGER_2)
+                  .select()
+                  .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
+                  .paths(PathSelectors.regex("/public.*"))
+                  .build()
+                  .groupName("springshop-public")
+                  .apiInfo(apiInfo());
+      }
+  
+      @Bean
+      public Docket adminApi() {
+          return new Docket(DocumentationType.SWAGGER_2)
+                  .select()
+                  .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
+                  .paths(PathSelectors.regex("/admin.*"))
+                  .build()
+                  .groupName("springshop-admin")
+                  .apiInfo(apiInfo());
+      }
+  ```
+  Now:
+  ```java
+      @Bean
+      public GroupedOpenApi publicApi() {
+          return GroupedOpenApi.builder()
+                  .setGroup("springshop-public")
+                  .pathsToMatch("/public/**")
+                  .build();
+      }
+  
+      @Bean
+      public GroupedOpenApi adminApi() {
+          return GroupedOpenApi.builder()
+                  .setGroup("springshop-admin")
+                  .pathsToMatch("/admin/**")
+                  .build();
+      }
+  ```
+   If you have **only one** `Docket` -- remove it and instead add properties to your `application.properties`:
+   ```properties
+  springdoc.packagesToScan=package1, package2
+  springdoc.pathsToMatch=/v1, /api/balance/**
+  ```
++ Add bean of `OpenAPI` type. See example:
+  ```java
+      @Bean
+      public OpenAPI springShopOpenAPI() {
+          return new OpenAPI()
+                  .info(new Info().title("SpringShop API")
+                  .description("Spring shop sample application")
+                  .version("v0.0.1")
+                  .license(new License().name("Apache 2.0").url("http://springdoc.org")))
+                  .externalDocs(new ExternalDocumentation()
+                  .description("SpringShop Wiki Documentation")
+                  .url("https://springshop.wiki.github.org/docs"));
+      }
+  ```
\ No newline at end of file