Solon v3.0.3

solon-docs-openapi2

</> markdown

此插件，由社区成员（Sorghum）贡献

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

1、描述

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

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

建议使用： solon-openapi2-knife4j

2、使用示例

  • 写个控制器输出 openapi json 结构，提供给相关工具使用。比如：apifox
@Controller
public class OpenApi2Controller {
    /**
     * swagger 获取分组信息
     */
    @Produces("application/json; charset=utf-8")
    @Mapping("swagger-resources")
    public String resources() throws IOException {
        return OpenApi2Utils.getApiGroupResourceJson();
    }

    /**
     * swagger 获取分组接口数据
     */
    @Produces("application/json; charset=utf-8")
    @Mapping("swagger/v2")
    public String api(Context ctx, String group) throws IOException {
        return OpenApi2Utils.getApiJson(ctx, group);
    }
}
  • 还要搞个配置器，把 DocDocket 产生
@Configuration
public class DocConfig {
    /**
     * 简单点的
     */
    @Bean("appApi")
    public DocDocket appApi() {
        //根据情况增加 "knife4j.setting" （可选）
        return new DocDocket()
                .groupName("app端接口")
                .schemes(Scheme.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(Scheme.HTTP, Scheme.HTTPS)
                .globalResponseInData(true)
                .globalResult(Result.class)
                .apis("com.swagger.demo.controller.admin"); //可以加多条，以包名为单位

    }
}
  • 现在可以简单的应用了（给接口上加注解，可以是最少量）
@Api("控制器")  //v2.3.8 之前要用：@Api(tags = "控制器")
@Mapping("/demo")
@Controller
public class DemoController {
    @ApiOperation("接口")
    @Mapping("hello")
    public Result hello(User user) { //以普通参数提交
        return null;
    }
    
    @ApiOperation("接口")
    @Post
    @Mapping("hello2")
    public Result hello2(@Body User user) { //以 json body 提交
        return null;
    }
}