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