|
| 1 | += log mapping lookup |
| 2 | + |
| 3 | +It is possible to let a processor log all the mapping lookups. It *may* be useful to understand why a mapping does not work. |
| 4 | + |
| 5 | +If a mapping doesn't work the first step is to check if the processor is applying it or if it ignores it. The mapping logging will report which mappings were selected for an OpenAPI type. |
| 6 | + |
| 7 | +If the processor doesn't select the mapping there may be something wrong with the mapping. Maybe a typo. |
| 8 | + |
| 9 | +In case the processor uses the mapping, but it still doesn't behave as expected it may be a bug. |
| 10 | + |
| 11 | +To control the logging there are two new xref:processor/configuration.adoc#_logging[logging options]. |
| 12 | + |
| 13 | +[source,yaml] |
| 14 | +---- |
| 15 | +openapi-processor-mapping: v10 |
| 16 | +options: |
| 17 | + package-name: io.openapiprocessor.generated |
| 18 | +
|
| 19 | +map: |
| 20 | + # ... |
| 21 | +
|
| 22 | +logging: |
| 23 | + mapping: true # <1> |
| 24 | + mapping-target: stdout #<2> |
| 25 | +---- |
| 26 | + |
| 27 | +<1> apart from enabling logging of the mapping lookups in the `mapping.yaml` you may want to set the `mapping-target`. |
| 28 | + |
| 29 | +<2> If set to `logger` the mapping lookup gets logged at `info` level to link:https://www.slf4j.org/[slf4j]. If set to `stdout` the mapping lookup gets written directly to `stdout` without slf4j. |
| 30 | + |
| 31 | +Enabling the logging will produce many blocks similar to: |
| 32 | + |
| 33 | +---- |
| 34 | +looking for any type mapping of name: 'foo2' path: GET '/fooA' type: 'array' A |
| 35 | + + global |
| 36 | + - parameters (type) |
| 37 | + - name: foo2 => java.util.List<java.lang.String> |
| 38 | + - name: bar => io.openapiprocessor.Bar1 |
| 39 | + - name: param @ io.openapiprocessor.ParamAnnotation |
| 40 | + - type: Bar @ io.openapiprocessor.ParamAnnotation |
| 41 | + + parameters (name) |
| 42 | + + name: foo2 => java.util.List<java.lang.String> |
| 43 | + - name: bar => io.openapiprocessor.Bar1 |
| 44 | + - name: param @ io.openapiprocessor.ParamAnnotation |
| 45 | + - type: Bar @ io.openapiprocessor.ParamAnnotation |
| 46 | +---- |
| 47 | + |
| 48 | +It always starts with a `looking for ..` followed by what it is looking for and the OpenAPI name or type to find, related to which path and its type. Then it lists all mappings checked with their location in the mapping file. |
| 49 | + |
| 50 | +In this case it looks for *any* mapping of `foo2`. *any* means that it is looking for any mapping, by testing all mappings by priority. More specific mappings have a higher priority and win. |
| 51 | + |
| 52 | +It did not find a mapping by its type (`array` in this case), but it found a name mapping for `foo2`, indicated by the `+` sign. The mappings that do not match get marked with a `-` sign. |
| 53 | + |
| 54 | +Here is a snippet from the OpenAPI yaml that is processed here. We have an endpoint `fooA` with a query parameter `foo2` of type `array`. |
| 55 | + |
| 56 | +[source,yaml] |
| 57 | +---- |
| 58 | + /fooA: |
| 59 | + get: |
| 60 | + summary: foo A summary. |
| 61 | + description: foo A endpoint |
| 62 | + tags: [foo] |
| 63 | + parameters: |
| 64 | + - in: query |
| 65 | + name: foo1 |
| 66 | + # ... |
| 67 | + - in: query |
| 68 | + name: foo2 |
| 69 | + description: parameter foo2 |
| 70 | + schema: |
| 71 | + type: array |
| 72 | + items: |
| 73 | + type: string |
| 74 | + - in: query |
| 75 | + name: bar |
| 76 | + # ... |
| 77 | + responses: |
| 78 | + '200': |
| 79 | + # ... |
| 80 | +---- |
| 81 | + |
| 82 | +The example is a small part of the link:https://github.com/openapi-processor/openapi-processor-base/tree/main/openapi-processor-core/src/testInt/resources/tests/map-many[`map many`] integration test. |
| 83 | + |
| 84 | + |
| 85 | +== maven |
| 86 | + |
| 87 | +Maven can handle both mapping targets. If the `mapping-target` is set to `logger` it is necessary to enable the mapping logger `io.openapiprocessor.core.converter.mapping` to see any output. |
| 88 | + |
| 89 | +For example by running `maven` with: |
| 90 | + |
| 91 | +---- |
| 92 | +./mvnw compile -Dorg.slf4j.simpleLogger.log.io.openapiprocessor.core.converter.mapping=info |
| 93 | +---- |
| 94 | + |
| 95 | +If the `mapping-target` is `stdout` the processor output will be written without the usual log level prefix. |
| 96 | + |
| 97 | + |
| 98 | +=== summary |
| 99 | + |
| 100 | +to enable logging with maven use: |
| 101 | + |
| 102 | +[source,yaml] |
| 103 | +---- |
| 104 | +openapi-processor-mapping: v10 |
| 105 | +options: |
| 106 | + package-name: ... |
| 107 | +
|
| 108 | +map: |
| 109 | + # ... |
| 110 | +
|
| 111 | +logging: |
| 112 | + mapping: true |
| 113 | + mapping-target: stdout |
| 114 | +---- |
| 115 | + |
| 116 | +to get the simple output, or |
| 117 | + |
| 118 | +[source,yaml] |
| 119 | +---- |
| 120 | +openapi-processor-mapping: v10 |
| 121 | +options: |
| 122 | + package-name: ... |
| 123 | +
|
| 124 | +map: |
| 125 | + # ... |
| 126 | +
|
| 127 | +logging: |
| 128 | + mapping: true |
| 129 | +---- |
| 130 | + |
| 131 | +to get the log level based output. Remember to enable the logger in this case as described above. |
| 132 | + |
| 133 | +== gradle |
| 134 | + |
| 135 | +Gradle requires the `mapping-target` to be `stdout`. Gradle can only globally enable log levels which is very noisy. The best option to log the mapping lookups is simply to write them to `stdout`. |
| 136 | + |
| 137 | +=== summary |
| 138 | + |
| 139 | +to enable logging with gradle use: |
| 140 | + |
| 141 | +[source,yaml] |
| 142 | +---- |
| 143 | +openapi-processor-mapping: v10 |
| 144 | +options: |
| 145 | + package-name: ... |
| 146 | +
|
| 147 | +map: |
| 148 | + # ... |
| 149 | +
|
| 150 | +logging: |
| 151 | + mapping: true |
| 152 | + mapping-target: stdout |
| 153 | +---- |
0 commit comments