【swagger】简单代码示例

第一步 引入swagger2依赖

<dependency>
<groupId> io.springfox groupId>
<artifactId> springfox-swagger2 artifactId>
<version> 2.9.2 version>
dependency>

<dependency>
<groupId> io.springfox groupId>
<artifactId> springfox-swagger-ui artifactId>
<version> 2.9.2 version>
dependency> 

第二步 启动类上添加@EnableSwagger2注解

/**
 * @EnableSwagger2 注解的作用
 * 是springfox提供的一个注解，代表swagger2相关技术开启
 * 会扫描当前类所在包，及子包中所有的类型中的注解
 * 做swagger文档的定制
 */
@SpringBootApplication
@EnableSwagger2 
public class TestApplication {
    public static void main(String[] args) {
        SpringApplication.run(TestApplication.class, args);
    }
}

第三步 编写一个简单的controller

@RestController
public class MyController {
    @RequestMapping("/get")
    public String get(){
        return "get";
    }
}

第四步 访问UI界面

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

如果启动失败，大概是springboot和swagger版本冲突，我用的springboot-2.5.6，swagger-2.7.0

启动成功，如下截图

自定义配置的基本信息

自定义注解

/**
 * @Target 描述当前的注解可以定义在什么资源上
 * 属性 value
 *  -定义具体的资源，包括
 *      -ElementType.METHOD 可以并以在方法上
 *      -ElementType.TYPE   可以定义在类上
 *      -ElementType.FIELD  可以定义的属性上
 *      -ElementType.PARAMETER  可以定义在方法参数上
 * @Retention 当前注解在什么时候生效
 * 属性 value
 *  - 定义具体的生效标记
 *      - RetentionPolicy.RUNTIME   运行时有效
 *      - RetentionPolicy.SOURCE    源码中生效
 *      - RetentionPolicy.CLASS     字节码有效
 *
 */
@Target({ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation4Swagger {
    // 自定义注解中的属性。相当于@MyAnnotation4Swagger(value="")
    String value() default "";
}

自定义配置

/**
 * Docket：摘要对象，通过对象配置描述文件的信息
 * apiInfo：设置描述文件中info。参数类型是ApiInfo
 * select()：返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象
 * ApiInfoBuilder：ApiInfo构建器
 */
@Configuration
public class SwaggerConfiguration {

    /**
     * 创建Docket类型的对象。并使用spring容器管理
     * Docket 是swagger中的全局配置对象
     */
    @Bean
    public Docket docket(){
        // 构建的是哪个版本的swagger
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        // API帮助文档的描述信息
        ApiInfo apiInfo = new ApiInfoBuilder()
                // 配置swagger文档主体内容
                .contact(new Contact(
                        "美行科技",// 文档的发布者
                        "www.meixingkeji.com",// 文档发布者的网站地址
                        "[email protected]")// 文档发布者的邮件地址
                )
                .title("swagger 框架学习帮助文档")
                .description("swagger 框架学习帮助文档(详细的描述信息)")
                .version("1.1.1")
                .build();

        // 给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);

        docket = docket
                .select()//获取Docket中的选择器。返回ApiSelectBuilder，构建选择器的。如：扫描什么包的注解
                // apis 方法可以写多个
                .apis(
                        // java8 工具类（and方法，or方法，并集，差集。。。）
                        Predicates.and(
                            Predicates.not(//取反 true-》false
                                    // 方法上有MyAnnotation4Swagger注解返回true
                                    RequestHandlerSelectors.withMethodAnnotation(MyAnnotation4Swagger.class)
                            ),
                            // 规则：扫描哪个包（包及其子包）
                            RequestHandlerSelectors.basePackage("com.mx.testSwagger.controller")
                        )
                )
                .paths(
                        Predicates.or(// 三个条件，任选其一
                                PathSelectors.regex("/swagger/.*"),
                                PathSelectors.regex("/swagger1/.*"),
                                PathSelectors.regex("/swagger2/.*")
                        )
                )// 使用正则表达式，约束生成API文档的路径地址
                .build();// apis 中需要配置扫描的规则

        return docket;
    }

}

常用注解

@Api(tags = {"HupfController","学习swagger的控制器"}) //给类设置别名
描述当前类型生成帮助文档的信息
属性：
	- tags：给当前类型定义别名，可以有多个。定义几个别名，在UI试图中就显示几个控制器访问链接
	- description：给当前类型生成的帮助文档定义一个描述信息


@ApiOperation(value = "处理POST",notes="post方法 用来进行数据新增操作")
使用在方法上，在UI界面显示方法的摘要和介绍


@ApiParam(name = "用户名",value = "新建的用户名", required = true)
使用在方法参数上


@ApiIgnore 
忽略，表示当前注解描述的方法不生成swagger


@ApiImplicitParams(value = {
            @ApiImplicitParam(name="m",value ="m参数描述",required=false,paramType="字符串",dataType="键值对"),
            @ApiImplicitParam(name="n",value ="n参数描述",required=true,paramType="字符串",dataType="键值对")
    })
使用在方法上，描述方法的参数列表

@ApiModel
描述一个实体类型，这个实体类如果称为任何一个生成API帮助文档方法的返回值类型的时候，此注解被解析

@ApiModelProperty
使用在实体类的属性上

示例代码如下：

@RestController
@Api(tags = {"HupfController","学习swagger的控制器"}) //给类设置别名
public class MyController {

    @ApiImplicitParams(value = {
            @ApiImplicitParam(name="m",value ="m参数描述",required=false,paramType="字符串",dataType="键值对"),
            @ApiImplicitParam(name="n",value ="n参数描述",required=true,paramType="字符串",dataType="键值对")
    })
    @GetMapping("/test")
    public String test(String m,String n){
        return "test";
    }


    @PostMapping("/swagger/post")
    @ApiOperation(value = "处理POST",notes="post方法 用来进行数据新增操作")
    public String post(
            @ApiParam(name = "用户名",value = "新建的用户名", required = true) String a,
            @ApiParam(name = "密码",value = "新建的密码", required = true)String b){
        return "post";
    }

    @GetMapping("/get")
    public String get(){
        return "get";
    }

    @ApiIgnore //忽略，表示当前注解描述的方法不生成swagger
    @MyAnnotation4Swagger //添加咱们自己创建的注解
    @RequestMapping("/req")
    public String req(String m){
        return "req";
    }
}

实体类

/**
 * @ApiModel 描述一个实体类型，这个实体类如果称为任何一个生成
 *          API帮助文档方法的返回值类型的时候，此注解被解析
 */
@ApiModel
public class MyBean implements Serializable {
    @ApiModelProperty(value="主键",name="主键（id）",required = false,example = "1",hidden = false)
    private String id;
    @ApiModelProperty(value="姓名",name="姓名（name）",required = false,example = "123456",hidden = false)
    private String name;
    @ApiModelProperty(value="密码",name="密码（password）",required = false,example = "xx-xx-xx",hidden = false)
    private String password;



    // 省略get、set方法
}