swagger

目录

• 文档地址
• swagger3
  • 文档展示请求头、回调
  • 单个参数文档
  • 自定义属性名，不按json配置的展示
  • 属性驼峰被转成下划线问题
  • 注解详解

文档地址

http://localhost:8080/swagger-ui.html

swagger3

文档展示请求头、回调

图片：

点击查看代码

    @Callback(name = "支付回调", operation = {@Operation(
                method = "post", summary = "支付回调请求体",
                    requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                        content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = CreateOrderCallbackRequestV2.class)
                        )
                    ),
                    responses = @ApiResponse(
                        description = "支付回调响应体",
                        responseCode = "204"
                    )
            )}, callbackUrlExpression = "{$request.body#/mer-url}"
    )
    @Parameters({
        @Parameter(name = "x-stucco-idempotency", description = "幂等性键,x-stucco-idempotency是由客"
            + "户端生成的唯一值，服务端用它来识别同一请求的后续重试。接口对x-stucco-idempotency的生成方式没有要"
            + "求。", in = ParameterIn.HEADER),
        @Parameter(name = "x-stucco-appid", in = ParameterIn.HEADER, description = "系统分配的appid"),
        @Parameter(name = "x-stucco-nonce", in = ParameterIn.HEADER, description = "随机字符串"),
        @Parameter(name = "x-stucco-timestamp", in = ParameterIn.HEADER, description = "毫秒时间戳"),
        @Parameter(name = "x-stucco-signature", in = ParameterIn.HEADER,
            description = "签名")
    })
    @Operation(summary = "后端创建预支付订单", description = "创建预支付订单 同一个商户订单ID('merchant_orde"
        + "r_num'),只会生成一个支付订单，如果相同的商户订单ID重复请求则会响应错误，除非使用相同的'x-st"
        + "ucco-idempotency '值。 接口依据header中的'x-stucco-idempotency '参数提供幂等性保证，携带相同'"
        + "x-stucco-idempotency '值的后续请求，接口会响应和第一次请求一样的结果(状态码，错误信息等)。")
    @PostMapping("/payment/order/create")

单个参数文档

@Parameter

• required = false不生效！
  解决办法：@RequestParam(name = "productTypeId", required = false) 添加属性。

自定义属性名，不按json配置的展示

对象按指定名称接受（不受转化影响）
加在属性上 @JsonProperty("paymentAmt")

属性驼峰被转成下划线问题

第1种办法（根本解决）：
针对swagger.core.v3依赖

点击查看代码

package com.yotta.yotta.core.json;

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import com.fasterxml.jackson.databind.SerializationFeature;
import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
import com.fasterxml.jackson.datatype.jdk8.Jdk8Module;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.fasterxml.jackson.module.paramnames.ParameterNamesModule;
import io.swagger.v3.core.jackson.ModelResolver;
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;

/**
 * jackson配置
 */
@Configuration
public class JacksonConfiguration implements Jackson2ObjectMapperBuilderCustomizer {

    @Override
    public void customize(Jackson2ObjectMapperBuilder jacksonObjectMapperBuilder) {
        //空字符转为null
        jacksonObjectMapperBuilder.featuresToEnable(
            DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT);
        jacksonObjectMapperBuilder.deserializerByType(String.class,
            new JacksonEmptyStringDeserializer());
        //未知属性报错关闭
        jacksonObjectMapperBuilder.featuresToDisable(
            DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
        //属性为null不序列化
        jacksonObjectMapperBuilder.serializationInclusion(JsonInclude.Include.ALWAYS);
        //属性命名自动转换为下划线方式
        jacksonObjectMapperBuilder.propertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
        //long转字符串
        jacksonObjectMapperBuilder.serializerByType(Long.class, ToStringSerializer.instance);
        //date转long
        jacksonObjectMapperBuilder.featuresToEnable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        //第三方模块
        jacksonObjectMapperBuilder.modules(new JavaTimeModule(), new Jdk8Module(),
            new ParameterNamesModule());
    }

    @Bean
    public ModelResolver modelResolver(ObjectMapper objectMapper) {
        return new ModelResolver(objectMapper);
    }
}

第2种办法：

// 1:加上name属性；2：注释掉@TableField；3：线上监测，属性名和字段是否查询、修改成功赋值。
@Schema(name = "goodsName",description = "商品名称")
// @TableField("goods_name")
private String goodsName;

注解详解

https://blog.csdn.net/weixin_44768189/article/details/115055784?ops_request_misc=&request_id=&biz_id=102&utm_term=org.springdoc:springdoc-openap&utm_medium=distribute.pc_search_result.none-task-blog-2_allsobaiduweb~default-0-115055784.142^v66control,201^v3control_1,213^v2t3_esquery_v1&spm=1018.2226.3001.4187