📝 Documentify

Documentify allows easy and convenient creation of OpenAPI specification documents through Kotlin DSL, making users from the complexity of traditional RestDocs. It combines the advantages of both Swagger and RestDocs for efficient and intuitive document management.

Installation and Getting Started

Installation

Add the following dependency to your build.gradle.kts file:

MVC

dependencies {
    implementation("io.github.bgmsound:documentify-starter-mvc:${version}")
}

WebFlux

dependencies {
    implementation("io.github.bgmsound:documentify-starter-reactive:${version}")
}

Getting Started

First, make your test class extends Documentify. and set up the test environment like this:

@BeforeEach
fun setUp(provider: RestDocumentationContextProvider) {
    testService = mockk()
    standalone(provider) {
        controllers(TestController(testService))
    }
}

You can also set up the test environment with an application context or an auto-configured MockMvc (or WebTestClient).

MVC Example

webApplicationContext(provider, context)
mockMvc(provider, mockMvc)

Reactive Example

applicationContext(provider, context)
webTestClient(provider, webTestClient)

And add the following code to your test class:

@BeforeEach
fun setUp(provider: RestDocumentationContextProvider) {
    standalone(provider) {
        controllers(TestController(testService))
    }
}

@Test
fun documentationGetApi() {
    every { testService.test() } returns SampleResponse("path", "test")
    
    documentation("test-get-api") {
        information {
            summary("test get api")
            description("this is test get api")
            tag("test")
        }
        requestLine(Method.GET, "/api/test/{path}") {
            pathVariable("path", "path", "path")
        }
        responseBody {
            field("testField1", "path", "path")
            field("testField2", "message", "test")
        }
    }
}

Additional validation of the mock response generated during the tests for document creation is also possible.

@Test
fun documentationGetApi() {
    documentation("test-get-api") {
        information {
            summary("test get api")
            description("this is test get api")
            tag("test")
        }
        requestLine(Method.GET, "/api/test/{path}")
        responseBody {
            field("testField", "test", "test")
        }
    }.expect(jsonPath("$testField").value("test"))
}

Generate OpenAPI Specification

After setting up the test environment and writing the test code, run the test. The OpenAPI specification document will be generated in the build/generated-snippets directory.

First, apply documentify plugin to your build.gradle.kts file (need gradle plugin portal):

plugins {
    id("io.github.bgmsound.documentify") version "${version}"
}

Then, write openapi configuration in your build.gradle.kts file:

openapi3 { 
    title = "Sample API"
    description = "This is a sample API documentation."
    version = "0.0.1"
    format = "yaml"
}

Finally, run the following command:

./gradlew openapi3
./gradlew openapi

you can also create Postman collection by running the following command:

./gradlew postman

---

[click to see more sample code]

Documentify Development Story

If you want to check out the development story of Documentify, please refer to the blog post.

License

documentify is Open Source software released under the Apache 2.0 license.