Merge pull request #21 from BGMSound/develop

[Feature] Support custom document emitter

Author: BGMSound

.github/workflows/deploy-to-mavencentral.yaml

@@ -11,7 +11,7 @@ on:
       MAVEN_CENTRAL_PASSWORD:
         required: true
 jobs:
-  publish-to-maven-central:
+  publish-to-mavencentral:
     runs-on: ubuntu-latest
     steps:
       - name: GitHub 리포지토리 체크아웃

README.md

@@ -1,4 +1,5 @@
 # 📝 Documentify
+[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0-blue.svg?logo=kotlin)](http://kotlinlang.org)
 ![Latest Release](https://img.shields.io/github/v/release/BGMSound/documentify)
 [![Apache 2.0 license](https://img.shields.io/badge/License-APACHE%202.0-green.svg?logo=APACHE&style=flat)](https://opensource.org/licenses/Apache-2.0)
 <br>
@@ -35,7 +36,7 @@ fun setUp(provider: RestDocumentationContextProvider) {
 ```
 You can also set up the test environment with an application context or an auto-configured MockMvc (or WebTestClient). 
 <br><br>
-`Mvc Example`
+`MVC Example`
 ```kotlin
 webApplicationContext(provider, context)
 mockMvc(provider, mockMvc)
@@ -77,11 +78,29 @@ fun documentationGetApi() {
 }
 ```
 
+Additional validation of the mock response generated during the tests for document creation is also possible.
+```kotlin
+@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:
+First, apply documentify plugin to your `build.gradle.kts` file *(need gradle plugin portal)*:
 ```kotlin
 plugins {
     id("io.github.bgmsound.documentify") version "${version}"
@@ -112,3 +131,6 @@ you can also create Postman collection by running the following command:
 
 ## Documentify Development Story
 If you want to check out the development story of Documentify, please refer to the [blog post](https://bgmsound.medium.com/documentify-선언형-rest-docs-dsl-제작기-0a09f651be2c).
+
+## License
+documentify is Open Source software released under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html).

build.gradle.kts

@@ -19,7 +19,7 @@ version = extra["project.version.id"] as String
 
 val publicModulePathSet = setOf(
     rootProject.projects.documentifyProject.documentifyCore.identityPath.path,
-    rootProject.projects.documentifyProject.documentifyPlugin.identityPath.path,
+    rootProject.projects.documentifyProject.documentifyGradlePlugin.identityPath.path,
     rootProject.projects.documentifyProject.documentifyMvc.identityPath.path,
     rootProject.projects.documentifyProject.documentifyReactive.identityPath.path,
     rootProject.projects.documentifyStarters.documentifyStarterMvc.identityPath.path,
@@ -67,7 +67,7 @@ subprojects {
         configure<MavenPublishBaseExtension> {
             publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
 
-            val artifactId = name.replace("-plugin", ".gradle.plugin")
+            val artifactId = name.replace("-gradle-plugin", ".gradle.plugin")
             val projectGroup = property("project.group").toString()
             val projectName = property("project.name").toString()
             val projectVersion = property("project.version.id").toString()

documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/AbstractDocumentEmitter.kt

@@ -10,8 +10,9 @@ import org.springframework.restdocs.snippet.Snippet
 
 abstract class AbstractDocumentEmitter(
     protected val provider: RestDocumentationContextProvider,
-    protected val documentSpec: DocumentSpec
-) {
+    protected val documentSpec: DocumentSpec,
+    protected val sampleAggregator: DocumentSpecSampleAggregator = DefaultDocumentSpecSampleAggregator
+) : DocumentEmitter {
     protected fun ResponseSpec.buildResource(index: Int): Snippet {
         val resourceBuilder = ResourceSnippetParameters.builder()
         if (documentSpec.tags.isNotEmpty()) {

documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/AbstractDocumentResult.kt

@@ -0,0 +1,48 @@
+package io.github.bgmsound.documentify.core.emitter
+
+import io.github.bgmsound.documentify.core.specification.element.field.Field
+import io.github.bgmsound.documentify.core.specification.schema.response.ResponseSpec
+
+abstract class AbstractDocumentResult : DocumentResult {
+    abstract fun validateJsonPath(jsonResultMatcher: JsonResultMatcher)
+
+    override fun validateWith(responseSpec: ResponseSpec) {
+        val matchers = aggregateMatchers(responseSpec.fields)
+        if (matchers.isEmpty()) {
+            return
+        }
+        matchers.forEach { matcher ->
+            validateJsonPath(matcher)
+        }
+    }
+
+    private fun aggregateMatchers(fields: List<Field>): List<JsonResultMatcher> {
+        return fields.filter {
+            it.hasSample() || it.canHaveChild() || !it.isIgnored()
+        }.flatMap {
+            it.aggregateMatchers()
+        }
+    }
+
+    private fun Field.aggregateMatchers(): List<JsonResultMatcher> {
+        if (isIgnored()) {
+            return emptyList()
+        }
+        if (!hasSample() && !canHaveChild()) {
+            return emptyList()
+        }
+        val matchers = mutableListOf<JsonResultMatcher>()
+        if (hasSample()) {
+            val jsonPath = StringBuilder("$.${path}").apply {
+                if (isArray()) {
+                    append("[*]")
+                }
+            }.toString().replace("[]", "[*]")
+            matchers.add(JsonResultMatcher.of(jsonPath, sample))
+        } else if (childFields().isNotEmpty())  {
+            val childMatchers = aggregateMatchers(childFields())
+            matchers.addAll(childMatchers)
+        }
+        return matchers
+    }
+}

…e/emitter/SpecElementSampleAssociater.kt …r/DefaultDocumentSpecSampleAggregator.ktdocumentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/SpecElementSampleAssociater.kt renamed to documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/DefaultDocumentSpecSampleAggregator.kt documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/SpecElementSampleAssociater.kt renamed to documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/DefaultDocumentSpecSampleAggregator.kt

@@ -3,16 +3,26 @@ package io.github.bgmsound.documentify.core.emitter
 import io.github.bgmsound.documentify.core.specification.element.SpecElement
 import io.github.bgmsound.documentify.core.specification.element.field.Field
 
-object SpecElementSampleAssociater {
-    fun List<Field>.associatedFieldSample(): Map<String, Any> {
-        return filter {
+object DefaultDocumentSpecSampleAggregator : DocumentSpecSampleAggregator {
+    @Suppress("UNCHECKED_CAST")
+    override fun <T : SpecElement> aggregate(specElements: List<T>): Map<String, Any> {
+        if (specElements.isEmpty()) {
+            return emptyMap()
+        }
+        if (!specElements.isField()) {
+            return specElements.associate {
+                it.key to it.sample
+            }
+        }
+        val fieldElements = specElements as List<Field>
+        return fieldElements.filter {
             it.hasSample() || it.canHaveChild() || !it.isIgnored()
         }.associate {
-            it.associatedSample()
+            it.aggregateSample()
         }
     }
 
-    fun Field.associatedSample(): Pair<String, Any> {
+    private fun Field.aggregateSample(): Pair<String, Any> {
         if (isIgnored()) {
             throw IllegalStateException("can't associate ignored field $key")
         }
@@ -25,7 +35,7 @@ object SpecElementSampleAssociater {
             if (childFields().isEmpty()) {
                 throw IllegalStateException("Field $key must have child fields")
             }
-            val sample = childFields().associate { it.associatedSample() }
+            val sample = childFields().associate { it.aggregateSample() }
             if (isArray()) {
                 listOf(sample)
             } else {
@@ -34,9 +44,9 @@ object SpecElementSampleAssociater {
         }
     }
 
-    fun List<SpecElement>.associatedSample(): Map<String, Any> {
-        return associate {
-            it.key to it.sample
+    private fun List<SpecElement>.isField(): Boolean {
+        return all {
+            it is Field
         }
     }
 }

documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/DocumentEmitter.kt

@@ -0,0 +1,3 @@
+package io.github.bgmsound.documentify.core.emitter
+
+interface DocumentEmitter

documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/DocumentResult.kt

@@ -0,0 +1,9 @@
+package io.github.bgmsound.documentify.core.emitter
+
+import io.github.bgmsound.documentify.core.specification.schema.response.ResponseSpec
+
+interface DocumentResult {
+
+    fun validateWith(responseSpec: ResponseSpec)
+
+}

documentify-project/documentify-core/src/main/kotlin/io/github/bgmsound/documentify/core/emitter/DocumentSpecSampleAggregator.kt

@@ -0,0 +1,9 @@
+package io.github.bgmsound.documentify.core.emitter
+
+import io.github.bgmsound.documentify.core.specification.element.SpecElement
+
+interface DocumentSpecSampleAggregator{
+
+    fun <T : SpecElement> aggregate(specElements: List<T>) : Map<String, Any>
+
+}