欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  IT编程

SwaggerUI日常使用

程序员文章站 2023-10-17 22:59:33
最近公司项目集成springFox,记录一些swaggerUI日常使用,包括数组,文件,默认值,允许值,参数/结果类注解,响应码..等等。 一.参数注解: 单参数:@ApiImplicitParam 多参数:@ApiImplicitParams 可以看一下参数注解接口相关属性如下: 下面详细介绍下几 ......

  最近公司项目集成springfox,记录一些swaggerui日常使用,包括数组,文件,默认值,允许值,参数/结果类注解,响应码..等等。

   一.参数注解:

  单参数:@apiimplicitparam

  多参数:@apiimplicitparams

1 @apiimplicitparams({
2             @apiimplicitparam(name = "pageindex",value = "页码,默认值:0",datatype = "int",
3                     paramtype = "query"),
4             @apiimplicitparam(name = "pagesize",value = "页长,默认值:20",datatype = "int",
5                     paramtype = "query")
6     })

  可以看一下参数注解接口相关属性如下:

 1 public @interface apiimplicitparam {
 2     //参数名
 3     string name() default "";
 4     //参数作用,对应中文名
 5     string value() default "";
 6     //默认值
 7     string defaultvalue() default "";
 8     //允许值的范围,逗号分隔
 9     string allowablevalues() default "";
10     //是否必传,可以看到默认是非必填的
11     boolean required() default false;
12     //暂时没用到
13     string access() default "";
14     //是否允许数组
15     boolean allowmultiple() default false;
16     //参数类型:int/string之类的,注:不支持integer
17     string datatype() default "";
18     //参数作用类型:比如query正常查询参数,path表示路径参数
19     string paramtype() default "";
20     //举例
21     string example() default "";
22 
23     example examples() default @example({@exampleproperty(
24     mediatype = "",
25     value = ""
26 )}); 

  下面详细介绍下几种应用:

  1.文件类型:

@apiimplicitparam(name = "file",value = "文件",datatype = "file",paramtype = "query")

  2.数组,以string数组为例

@apiimplicitparam(name = "type",value = "类型",datatype = "string",  paramtype = "query",allowmultiple = true),

  3.默认值

 @apiimplicitparam(name = "type",value = "类型",datatype = "string",paramtype = "query",defaultvalue = "test"),

  4.允许值,比如状态,开关类字段,一般只支持0/1

@apiimplicitparam(name = "status",value = "状态",datatype = "int",paramtype = "query",allowablevalues = "0,1"),

       5.参数/结果类注解 一般常用@requestbody封装的参数类,或者设定的结果类。

public void create(@apiparam @requestbody entity entity)

  然后在对应的参数类中添加响应的@apimodel和@apiproperty注解   

@apimodel
public class entity {
    @apimodelproperty(name = "id",value = "主键")
    private int id;                                     

    @apimodelproperty(name = "type",value = "类型",)
    private string type;                                
}

  6.响应码

@apiresponses({
            @apiresponse(code = 200,message = "操作成功"),
                    
    })

  在swaggerui界面的model中可以看到生成效果,这里我只加了前两个注解  

SwaggerUI日常使用

  7.必填项,默认非必填。注:必填项一定要和接口设定一致。 

@apiimplicitparam(name = "id",value = "id",datatype = "string", paramtype = "query",required = true)

  8.路径参数,比如接口路径为 /type/{id},可以如下定义注解 

@apiimplicitparam(name = "id",value = "id",datatype = "string", paramtype = "path",required = true)

 

 

待补充...