0010.SpringDoc-Openapi Swagger相关

1.自定义Map类型的输出格式

配置输出格式

@Configuration
public class OpenApiConfig2 {

    @Bean
    public OpenAPI openAPI() {
        OpenAPI openApi = new OpenAPI();
        // 设定基础信息
        openApi.info(new Info()
                .title("title")
                .description("description")
                .version("v1"));
        
        // 设定Map类型的输出格式
        MapSchema mapSchema = new MapSchema();
        
        ResolvedSchema resolvedSchema = ModelConverters.getInstance()
                .resolveAsResolvedSchema(new AnnotatedType(MapValueXXX.class).resolveAsRef(false));
        
        mapSchema.addProperties("map key description", resolvedSchema.schema);
        openApi.components(new Components().addSchemas("MapSchemaXXX", mapSchema));// control中需要使用的名字
        return openApi;
    }
}

在Control中使用

@ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "操作成功", content = @Content(schema = @Schema(ref = "#/components/schemas/MapSchemaXXX")))
    })

2.自定义LocalDateTime类型输出格式

@Component
public class OpenApiSchemaCustomiser extends SpecFilter implements OpenApiCustomiser {
    @Override
    @SuppressWarnings("all")
    public void customise(OpenAPI openApi) {
        Map<String, Schema> schemaMap = openApi.getComponents().getSchemas();
        for (Schema schema : schemaMap.values()) {
            this.convertDateTimeFormat(schema);
        }
    }
    
    @SuppressWarnings("all")
    private void convertDateTimeFormat(Schema schema) {
        Map<String, Schema> properties = schema.getProperties();
        if (properties == null) {
            properties = Map.of();
        }
        for (String propertyName : properties.keySet()) {
            Schema propertySchema = properties.get(propertyName);
            if (propertySchema instanceof DateTimeSchema) {
                Schema strSchema = new StringSchema()
                        .example("2022-05-19 10:35:17.000")
                        .pattern("<yyyy-MM-dd HH:mm:ss.SSS>")
                        .description(propertySchema.getDescription());
                properties.replace(propertyName, strSchema);
            } else if ( propertySchema instanceof ObjectSchema) {
                this.convertDateTimeFormat(propertySchema);
            }
        }
    }
}

3.生成json，yaml文件

3.1.启动SpringBoot
3.2.浏览器中输入

http://localhost:9080/v3/api-docs/
http://localhost:9080/v3/api-docs.yaml
http://localhost:9080/swagger-ui.html （这个需要引入ui包）

4.yaml2html

npm i -g redoc-cli
redoc-cli build api-docs.yaml