Swagger2注解（个人使用）

其他 2020-09-07 13:26:13 阅读次数: 0

导入依赖

由于使用了另外一个UI界面所有导入的依赖多了一个。

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.10.5</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-spring-webmvc</artifactId>
            <version>2.10.5</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.10.5</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

配置类编写

package top.ddandang.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.ArrayList;


/**
 * <p>
 * 配置Swagger
 * </p>
 *
 * @author D
 * @version 1.0
 * @date 2020/6/9 16:30
 */

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    /**
     * 配置swagger Docket实例
     * @return 返回Docket 对象
     */
    @Bean
    public Docket docket(Environment environment) {

        // 配置使用环境
        Profiles profiles = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(
                // 使用的swagger版本
                DocumentationType.SWAGGER_2)
                // 显示的信息
                .apiInfo(apiInfo())
                // 在dev环境使用
                .enable(flag)
                .select()
                // 指定扫描的包
                .apis(RequestHandlerSelectors.basePackage("top.ddandang.swagger.controller"))
                .build();
    }

    /**
     * 配置swagger 信息 apiInfo
     * @return ApiInfo 配置信息
     */
    private ApiInfo apiInfo() {

        //作者信息
        Contact contact = new Contact("D", "www.ddandang.top", "[email protected]");

        return new ApiInfo(
                // 标题
                "测试Swagger2 API",
                // 描述
                "D",
                // 版本号
                "1.0",
                // 服务条款网址
                "urn:tos",
                // 作者信息
                contact,
                // 许可
                "Apache 2.0",
                // 许可证网址
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

访问页面

swagger自带UI

http://localhost:7070/swagger-ui.html
在这里插入图片描述
第三方UI

http://localhost:7070/doc.html
在这里插入图片描述

常用注解

@Api

常用属性

属性 类型 作用
@Api 作用范围 类
value String 用于描述类的作用（不会在UI界面显示）
tags String[] 对该类（里面全部的接口）进行分组

value
用于描述类的作用（不会在UI界面显示）

@RestController
@RequestMapping("/admin")
@Api(value = "Admin控制器")
public class AdminController {

    @GetMapping("/login")
    public R login() {
        return R.failed();
    }

    @GetMapping("/register")
    public R register() {
        return R.failed();
    }
}

tags
如果两个类的tags相同，那么两个类下的所有接口会在一个标签下展示。

@RestController
@RequestMapping("/admin")
@Api(value = "Admin控制器", tags = {"用户操作", "管理员操作"})
public class AdminController {

    @GetMapping("/login")
    public R login() {
        return R.failed();
    }

    @GetMapping("/register")
    public R register() {
        return R.failed();
    }
}


@RestController
@Api(value = "用户操作的接口", tags = {"用户操作"})
@RequestMapping("/user")
public class UserController {

    @GetMapping("/login")
    public R login() {
        return R.success();
    }
}

image-20200820153749797

@ApiIgnore

忽略整个类在UI界面的显示，或者某个方法，方法的某个参数。

常用属性

属性 类型 作用
@ApiIgnore 作用范围 类，方法，接口的参数
value String 关于为什么忽略此参数/操作的简短说明 
@RestController
@RequestMapping("/admin")
@Api(value = "Admin控制器", tags = {"用户操作", "管理员操作"})
public class AdminController {

    @ApiIgnore
    @GetMapping("/login")
    public R login() {
        return R.failed();
    }

    @GetMapping("/register")
    public R register(@ApiIgnore(value = "没用的参数") String username, String password) {
        return R.failed();
    }
}

@ApiIgnore(value = "不需要显示的类")
@RestController
@Api(value = "用户操作的接口", tags = {"用户操作"})
@RequestMapping("/user")
public class UserController {

    @GetMapping("/login")
    public R login() {
        return R.success();
    }
}

image-20200820154636886

@ApiOperation

说明该方法的作用的用途，作用于方法上

常用属性

属性 类型 作用
@ApiOperation 作用范围 方法，类（不常用）
value String 此操作的简要说明
notes String 该操作的详细描述
tags String[] 和@Api注解的tags参数一致，对接口进行逻辑分类 
@RestController
@Api(value = "用户操作的接口", tags = {"用户操作"})
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "用户登录接口", notes = "用户使用账号密码进行登录", tags = {"登录"})
    @PostMapping("/login")
    public R login(String username, String password) {
        return R.success();
    }

    @ApiOperation(value = "用户注册接口", notes = "用户使用账号密码进行登录", tags = {"注册"})
    @PostMapping("/register")
    public void register(String username, String password) {

    }
}

@RestController
@RequestMapping("/admin")
@Api(value = "Admin控制器", tags = {"用户操作", "管理员操作"})
public class AdminController {


    @ApiOperation(value = "管理员登录接口", notes = "用户使用手机号和密码进行登录", tags = {"登录"})
    @PostMapping("/login")
    public R login(String phone, String password) {
        return R.failed();
    }

    @PostMapping("/register")
    public R register(@ApiIgnore(value = "没用的参数") String username, String password) {
        return R.failed();
    }
}

value和notes属性

image-20200820160425265

@ApiImplicitParams

需要与@ApiImplicitParam一起使用，用于描述接口的各个参数

属性 类型 作用
@ApiImplicitParams 作用范围 方法，与@ApiImplicitParam联合使用
value ApiImplicitParam[]

@ApiImplicitParam

常用属性

属性 类型 作用
@ApiImplicitParam 作用范围 方法
name String 参数名称
value String 参数的简要说明
defaultValue String 描述参数的默认值
required boolean 参数是否是必须的
dataType String 参数的数据类型（String，Integer等）为Integer的时候传参会失败，建议封装实体类进行传递大于2个的参数
paramType String 参数请求方式（query，path）不常用：body，header，form
query:对应@RequestParam ? 传递
path: 对应@PathVariable{} path 传递

@RestController
@Api(value = “用户操作的接口”, tags = {“用户操作”})
@RequestMapping("/user")
public class UserController {

@ApiOperation(value = "用户登录接口", notes = "用户使用账号密码进行登录", tags = {"登录"})
@PostMapping("/login")
public R login(String username, String password) {
    return R.success();
}

@ApiOperation(value = "用户注册接口", notes = "用户使用账号，密码和年龄进行注册", tags = {"注册"})
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "账号", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "password", value = "密码", defaultValue = "123456", required = true, dataType = "String", paramType = "query")
})
@PostMapping("/register")
public R register(String username, String password) {

    Map<String, Object> map = new HashMap<>();
    map.put("username", username);
    map.put("password", password);
    return R.success().data(map);
}

}

image-20200820164921293

@ApiResponses

需要与@ApiResponse一起使用，用于描述接口方法或类操作的可能响应。

属性 类型 作用
@ApiResponses 作用范围 方法和类，与@ApiResponse联合使用
value ApiResponse[]

@ApiResponse

常用属性

属性 类型 作用
@ApiResponse 作用范围 @ApiResponses内部
code int 响应的HTTP状态代码
message String 响应信息（描述） 
@ApiOperation(value = "管理员注册接口", notes = "管理员使用账号，密码进行注册", tags = {"注册"})
@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "账号", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "password", value = "密码", defaultValue = "123456", required = true, dataType = "String", paramType = "query"),
        @ApiImplicitParam(name = "confirmPassword", value = "确认密码", defaultValue = "123456", required = true, dataType = "String", paramType = "query")
})
@ApiResponses(value = {
        @ApiResponse(code = 2000, message = "请求成功"),
        @ApiResponse(code = 4000, message = "请求错误"),
        @ApiResponse(code = 4001, message = "两次密码不一致")
})
@PostMapping("/register")
public R register(@ApiIgnore(value = "没用的参数") String username, String password, String confirmPassword) {

    Map<String, Object> map = new HashMap<>();
    map.put("username", username);
    map.put("password", password);
    map.put("confirmPassword", password);
    if (!password.equals(confirmPassword)) {
        return R.failed().code(4001).message("两次密码不一致");
    }
    return R.success().data(map);
}

image-20200820170541214

@ApiModel

表示对类进行说明，用于参数用实体类接收

属性 类型 作用
@ApiModel 作用范围 类
value String 为类其别名，默认情况下，使用类名
description String 提供类的详细说明。 
@ApiModel(value = "newAdmin", description = "用户接受用户注册的参数封装的实体类")
@Data
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
public class Admin implements Serializable {
    private String name;
    private String username;
    private String password;
}

@RestController
@RequestMapping("/admin")
@Api(value = "Admin控制器", tags = {"用户操作", "管理员操作"})
public class AdminController {
    @ApiOperation(value = "管理员注册接口", notes = "管理员使用账号，密码进行注册(使用实体类接受)", tags = {"注册"})
    @ApiResponses(value = {
            @ApiResponse(code = 2000, message = "请求成功"),
            @ApiResponse(code = 4000, message = "请求错误"),
            @ApiResponse(code = 4001, message = "两次密码不一致")
    })
    @PostMapping("/newRegister")
    public R newRegister(@RequestBody Admin admin) {
        return R.success().data("admin", admin);
    }
}

image-20200820171447298

@ApiModelProperty

对model属性进行说明

属性 类型 作用
@ApiModelProperty 作用范围 字段（常用），方法
value String 这个属性的简短说明
name String 重写属性的名称（没用过。。。）
required boolean 指定的参数是必需的或没有。
hidden boolean 隐藏改属性 
@ApiModel(description = "用户接受用户注册的参数封装的实体类")
@Data
@Accessors(chain = true)
@AllArgsConstructor
@NoArgsConstructor
public class Admin implements Serializable {

    @ApiModelProperty(value = "姓名", required = true)
    private String name;

    @ApiModelProperty(value = "账号", required = true, hidden = true)
    private String username;

    @ApiModelProperty(value = "密码", required = true)
    private String password;
}

image-20200820172252090
image-20200820172347561

其他说明

个人swagger.md文件
HTTP状态代码定义

可以将接口信息直接导出markdown

加粗样式

猜你喜欢

转载自blog.csdn.net/d875708765/article/details/108128755
今日推荐
开源日报 | Chrome内置Gemini的意义不在于Gemini；中国AI追随之路的五大误区；ECharts创始人“下海”养鱼；谷歌I/O开发者大会什么都有，只是没有惊喜
微软回应中国区AI团队“打包赴美”传闻
基于大语言模型的开源知识库问答系统 MaxKB GitHub Star 数量突破 5,000 个！
美国拟限制 AI 大模型出口中国和俄罗斯
苹果将与 OpenAI 达成协议，将 ChatGPT 应用于 iPhone
openKylin 社区生态委员会第六次会议圆满召开
阿里云正式发布通义千问 2.5
Python 3.13 发布首个 Beta：实验性自由线程模式和 JIT、改进交互式解释器
Stack Overflow 拿我的代码去训练 AI 大模型，还封了我的账号
Pop!_OS 的 COSMIC 桌面完成 App Store 上架工作
《2024 年一季度互联网投融资运行情况》研究报告
报告：Django 仍然是 74% 开发者的首选
周排行
laravle中orm简单的增删改查
文本分类 特征选取之CHI开方检验
Spark核心编程-WordCount
大数据开发实战系列之电信客服(1)
读书笔记 - 把时间当作朋友 by 李笑来
python 笔记--if else
SpringBoot/Mybatis/Druid, 多数据源MultiDataSource配置思路
排序三个整数
redis集群搭建【2】-Windows中Redis集群搭建
STM32F030驱动TM1650点亮4联数码管
每日归档
更多
2024-05-16(6)
2024-05-15(24)
2024-05-14(0)
2024-05-13(18)
2024-05-12(0)
2024-05-11(38)
2024-05-10(38)
2024-05-09(35)
2024-05-08(42)
2024-05-07(14)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022