27 Temmuz 2022 Çarşamba

Swagger @Schema Anotasyonu

Giriş
Şu satırı dahil ederiz
import io.swagger.v3.oas.annotations.media.Schema;
Örnek
Şöyle yaparız
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data; @Data @Schema(name="Book", description="Book characteristic") public class Book { @Schema(description="Book Tittle", maxLength=50) private String title; private String[] authors; }

SpringDoc OpenAPI Kullanımı

springdoc-openapi Nedir?
Açıklaması şöyle. Yani aslıda OpenAPI gerçekleştirimi diyebiliriz. OpenAPI REST noktaları için 
1. JSON veya
2. YAML
dokümantasyonu üretir
springdoc-openapi is a library that automatically generates documentation for OpenAPI compliant REST APIs built with Spring. It inspects an application’s code at runtime, looking at HTTP endpoints, their annotations, and returned objects and uses this information to generate documentation.

The library provides support for standard (don’t know what to really call this) Spring web code (e.g. endpoints defined in @RestControllers/@Controllers) and Spring Webflux.

To top everything off, springdoc-openapi can start a Swagger UI based on the documentation it generates, making it even easier for users to understand and interact with your APIs.
Ancak bu kütüphaneye ilave olarak bir şey daha kullanılıyor. O da swagger-annotations kütüphanesi. Bu kütüphane için ek bir maven dependency gerekmiyor. Açıklaması şöyle. Swagger ise REST noktaları için kullanması kolay ekranlar üretir.
As mentioned above, you will miss out on a lot of documentation if you rely on springdoc-openapi to do everything without you giving it a helping hand.

Luckily, another library provides ways to add this extra documentation that is compatible with springdoc-openapi. The swagger-annotations library gives you access to numerous additional annotations (as the name suggests) to document your APIs as the OpenAPI specification wants you to do.

You will have access to swagger-annotations without further changes as it is an API dependency of springdoc-openapi.
Maven
springdoc-openapi-v1 için şu satırı dahil ederiz
<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>1.7.0</version>
 </dependency>
springdoc-openapi-v2 ve Spring 3 ile şu satırı dahil ederiz
<dependency>
<groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.0.2</version> </dependency>
Swagger UI
Açıklaması şöyle
The generated documentation can then be accessed by a Swagger UI which is started by default when using springdoc-openapi and is accessible by going to <server:port>/swagger-ui.html, which will redirect you to a slightly different URL straight after (<server:port>/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config). Going to /swagger-ui/index.html will instead display Swagger’s pet store example, which probably isn’t what you wanted to see.
Swagger çıktıyı görmek için şu adrese gideriz 
http://localhost:8080/swagger-ui/index.html
Şeklen şöyle. Ekran tasarımı şöyle
1. Başlık
2. Controller listesi
3. Controller tarafından kullanılan nesnelerin listesi yani Schemas.
Benim yaptığım bir örnek şöyle


application.properties
Açıklaması şöyle
Springdoc-openapi also supports swagger-ui properties. These can be used as Spring Boot properties, with the prefix springdoc.swagger-ui.
Örnek
Open API URL'sini değiştirmek için şöyle yaparız
springdoc.api-docs.path=/docs/v3/api-docs
Örnek
Swagger URL'sini değiştirmek için şöyle yaparız
springdoc.swagger-ui.path=/swagger-ui-custom.html
Örnek
Şöyle yaparız
springdoc.swagger-ui.operationsSorter=method
Maven Plugin - openapi.json
Açıklaması şöyle
Bu plugin ile yaml veya json dosyaları üretilir. Böylece bu dosya Postman, Insomnia veya benzeri araçlara ithal edilebilir. Dosya şöyle bir şey
{
  "paths": {
    "/jobs/{groupId}/{jobId}": {
      "delete": {
        "tags": [
          "api-controller"
        ],
        "operationId": "deleteJob",
        "parameters": [
          {
            "name": "groupId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        }
      }
    }
  }
}
Örnek
Şöyle yaparız
<plugin>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-maven-plugin</artifactId>
  <version>1.1</version>
  <executions>
    <execution>
      <id>integration-test</id>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>
Çalıştırmak için şöyle yaparız. Böylece openapi.json dosyası üretilir
mvn verify
Gradle Plugin - openapi.json
Örnek
Şöyle yaparız
plugins {  
  id("org.springdoc.openapi-gradle-plugin") version "1.4.0"  
  id("org.openapi.generator") version "6.1.0" 
}
Şöyle yaparız
// Define a custom openApi task to start Spring and write the OpenAPI spec 
//to the build directory.
openApi { 
  customBootRun { 
    args.set(listOf("--spring.profiles.active=openapi")) 
  } 
}

When we run ./gradlew generateOpenApiDocs an openapi.json file 
will be written to the build directory.
Daha sonra şöyle yaparız
// Now we can generate an OpenAPI client using a gradle task:
openApiGenerate { 
  generatorName.set("java") 
  version.set(System.getenv("CLIENT_VERSION")) 
  id.set("yourid") 
  groupId.set("yourgroup") 
  inputSpec.set("$buildDir/openapi.json") 
  outputDir.set("$buildDir/client") 
  configOptions.set(mapOf( "dateLibrary" to "java8" )) 
}

//Run the command like so ./gradlew openApiGenerate to write 
//a client into the build/client directory. 
@ApiResponses Anotasyonu
@ApiResponses Anotasyonu yazısına taşıdım

@Operation Anotasyonu
@Operation Anotasyonu yazısına taşıdım

@OpenAPIDefinition Anotasyonu
@OpenAPIDefinition Anotasyonu yazısına taşıdım

OpenAPI Sınıfı
OpenAPI Sınıfı yazısına taşıdım