solon-docs-openapi3 [试用]

此插件，主要社区贡献人（ingrun）

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-docs-openapi3</artifactId>
</dependency>

1、描述

（v3.8.1 后支持）文档基础插件，可生成文档模型。一般不直接使用（因为没有提供界面，只有本地接口）。

• 本插件，用于生成文档模型
• 界面插件，提供交互界面

建议使用： solon-openapi3-knife4j

2、使用示例

• 写个控制器输出 openapi json 结构，提供给相关工具使用。比如：apifox

import org.noear.solon.annotation.Controller;
import org.noear.solon.annotation.Mapping;
import org.noear.solon.annotation.Produces;
import org.noear.solon.core.handle.Context;
import org.noear.solon.docs.openapi3.OpenApi3Utils;

import java.io.IOException;

@Controller
public class OpenApi3Controller {
    /**
     * swagger 获取分组信息
     */
    @Produces("application/json; charset=utf-8")
    @Mapping("swagger-resources")
    public String resources() throws IOException {
        return OpenApi3Utils.getApiGroupResourceJson();
    }

    /**
     * swagger 获取分组接口数据
     */
    @Produces("application/json; charset=utf-8")
    @Mapping("swagger/v3")
    public String api(Context ctx, String group) throws IOException {
        return OpenApi3Utils.getApiJson(ctx, group);
    }
}

• 还要搞个配置器，把 DocDocket 产生

import org.noear.solon.annotation.Configuration;
import org.noear.solon.annotation.Bean;
import org.noear.solon.core.handle.Result;
import org.noear.solon.docs.DocDocket;
import org.noear.solon.docs.models.ApiContact;
import org.noear.solon.docs.models.ApiInfo;

@Configuration
public class DocConfig {
    /**
     * 简单点的
     */
    @Bean("appApi")
    public DocDocket appApi() {
        //根据情况增加 "knife4j.setting" （可选）
        return new DocDocket()
                .groupName("app端接口")
                .schemes("http")
                .apis("com.swagger.demo.controller.app");

    }

    /**
     * 丰富点的
     */
    @Bean("adminApi")
    public DocDocket adminApi() {
        //根据情况增加 "knife4j.setting" （可选）
        return new DocDocket()
                .groupName("admin端接口")
                .info(new ApiInfo().title("在线文档")
                        .description("在线API文档")
                        .termsOfService("https://gitee.com/noear/solon")
                        .contact(new ApiContact().name("demo")
                                .url("https://gitee.com/noear/solon")
                                .email("demo@foxmail.com"))
                        .version("1.0"))
                .schemes("http", "https")
                .globalResponseInData(true)
                .globalResult(Result.class)
                .apis("com.swagger.demo.controller.admin"); //可以加多条，以包名为单位

    }
}

• 现在可以简单的应用了（给接口上加注解，可以是最少量）

import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import org.noear.solon.annotation.Body;
import org.noear.solon.annotation.Controller;
import org.noear.solon.annotation.Mapping;
import org.noear.solon.annotation.Post;
import org.noear.solon.core.handle.Result;

@Tag(name ="控制器")
@Mapping("/demo")
@Controller
public class DemoController {
    @Operation(summary = "接口")
    @Mapping("hello")
    public Result hello(User user) { //以普通参数提交
        return null;
    }

    @Operation(summary = "接口")
    @Post
    @Mapping("hello2")
    public Result hello2(@Body User user) { //以 json body 提交
        return null;
    }
}