心耘博客 | ZLPRIME-磊落平生志,破浪去乘风 心耘博客 | ZLPRIME-磊落平生志,破浪去乘风
  • 首页
  • 朝花夕拾
    • 光影记录
    • 生活随笔
  • 代码如诗
    • 100 Days of SwiftUI
    • 后端技术
    • 服务器配置
  • 影集
  • 关于我
  • 更多
    • 专题汇总
    • 友情链接
    • 留言板
  • 0
  • 0

Swagger的基本使用

心耘
3 年前

Swagger2可以通过注解快速帮助我们编写最新的API接口文档。我们只需要按照它的规范去定义接口及接口相关的信息,就可以做到生成各种格式的接口文档,以及在线接口调试页面等。使用Swagger2首先要导入它的maven坐标:

  <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
  </dependency>

导入了依赖坐标以后,我们就可以在项目中使用Swagger2帮我们生成接口文档了。我们要先熟悉一下Swagger2的常用注解:

然后,我们要创建一个实体类User和控制器UserController,并在上面添加相应的Swagger注解

注解说明
@Api用在请求的类上,例如Controller,表示对类的说明
@ApiModel用在类上,通常是实体类,表示一个返回响应数据的信息
@ApiModelProperty用在属性上,描述响应类的属性
@ApiOperation用在请求的方法上,说明方法的用途、作用
@ApiImplicitParams用在请求的方法上,表示一组参数说明
@ApiImplicitParam用在@ApiImplicitParams注解中,指定一个请求参数的各个方面

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(value = "用户实体",description = "用户实体")
public class User {
    @ApiModelProperty(value = "主键")
    private int id;
    @ApiModelProperty(value = "姓名")
    private String name;
    @ApiModelProperty(value = "年龄")
    private Integer age;
    @ApiModelProperty(value = "地址")
    private String address;
}
Swagger的基本使用
@RestController
@RequestMapping("/users")
@Api(tags = "用户控制器")
public class UserController {
    @GetMapping
    @ApiOperation(value = "查询所有用户",notes = "查询所有用户信息")
    public List<User> getAllUsers(){
        User user = new User();
        user.setId(100);
        user.setName("zhang");
        user.setAge(27);
        user.setAddress("安徽省合肥市");
        List<User> users = new ArrayList<>();
        users.add(user);
        return users;
    }
  
    @DeleteMapping("/{id}")
    @ApiImplicitParams(  //对参数的说明如:是否必需,参数类型,参数名称
            @ApiImplicitParam(name = "id",value = "用户编号",required = true,type = "Integer")
    )
    @ApiOperation(value = "删除用户", notes = "删除用户信息")
    public String delete(@PathVariable int id){
        return "OK";
    }
 }
Swagger的基本使用
Swagger的基本使用

创建好实体类和控制器以后,我们接着在SpringBoot项目中,创建Swagger的自动配置类SwaggerAutoConfiguration。这个类的作用是在里面设置一些Swagger的配置信息,并通过Spring框架进行自动加载。

/*
* Swagger2配置类
* */
@Configuration
@EnableSwagger2  //开启Swagger2,这个注解很关键
public class SwaggerAutoConfiguration {

    //配置Swagger接口文档的基本信息
    private ApiInfo apiInfo = new ApiInfoBuilder()
            .title("SwaggerAPI文档标题")  //设置接口文档的标题
            .version("1.0.1")           //设置接口文档的版本
            .contact(new Contact("zlprime","https://www.zlprime.cn","zl_al@test.com")) //设置接口文档的联系信息,需要是Contact类,在类中set联系人的姓名,url和email
            .description("这是一个API文档,遇到接口问题时请及时与后端同学联系") //设置接口文档的描述信息
            .build();


    private Docket createRestApi(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zlprime.controller")) //设置Swagger的包扫描路径
                .build();
        return docket;
    }
}
Swagger的基本使用

在application.yml文件中,配置一下swagger的访问端口

server:
  port: 9001

最后创建Springboot的启动类SwaggerApplication:

/*
* Swagger启动类
* */
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class);
    }
}

启动之后,访问地址是 localhost:端口号/swagger-ui/index.html

java spring
0
Lombok的使用
上一篇
Knife4J的基本使用
下一篇

评论 (0)

再想想
暂无评论

心耘

73
文章
167
评论
94
喜欢

标签

centos (13) java (22) jenkins (7) linux (12) lombok (1) maven (1) mysql (3) redis (2) rocky linux (3) spring (8) wordpress (5) 发布 (3) 实用技巧 (7) 教程 (6) 服务器配置 (3) 生活 (5) 部署 (2)

聚合文章

生活杂记(一)
家电选购小结-空调
十一带娃心得
通过War包升级Jenkins版本

专题推荐

7

Jenkins合集

12

服务器配置

猜你喜欢

通过War包升级Jenkins版本

通过War包升级Jenkins版本

1 年前
429 0 0
配置Jmeter的Perfmon插件

配置Jmeter的Perfmon插件

2 年前
555 0 0
为JMeter安装插件

为JMeter安装插件

2 年前
555 0 0
Mac中安装并启动Jmeter

Mac中安装并启动Jmeter

2 年前
727 0 2

简介

海边微风起,等风也等你

留言板

留言板

小伙伴们

2Broear 乙末博客 若志随笔 豆豆 诗意笔记 元のDiary
Copyright © 2017-2025 心耘博客 | ZLPRIME-磊落平生志,破浪去乘风. 皖ICP备17019582号
  • 首页
  • 朝花夕拾
    • 光影记录
    • 生活随笔
  • 代码如诗
    • 100 Days of SwiftUI
    • 后端技术
    • 服务器配置
  • 影集
  • 关于我
  • 更多
    • 专题汇总
    • 友情链接
    • 留言板

搜索

  • java
  • spring

心耘

73
文章
167
评论
94
喜欢