• 首页
  • 朝花夕拾
    • 摄影
    • 生活
    • 随笔
  • 编程学习
    • Java
    • Vue
    • WordPress
  • 其它
    • 游记地图
    • 闲言碎语
    • 友情链接
    • 留言板
首页 › 编程学习 › Java › Swagger的基本使用

Swagger的基本使用

Stone
1年前Java
1,142 0 0

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;
}
@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";
    }
 }

创建好实体类和控制器以后,我们接着在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;
    }
}

在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 java框架 spring
0
本文系作者 @Stone 原创发布在 。未经许可,禁止转载。
Lombok的使用
上一篇
Knife4J的基本使用
下一篇
评论 (0)
再想想
聚合文章
配置Jmeter的Perfmon插件
2月前
Rocky Linux中设置盒盖不休眠
2月前
为JMeter安装插件
2月前
Mac中安装并启动Jmeter
2月前
相关文章
配置Jmeter的Perfmon插件
为JMeter安装插件
Mac中安装并启动Jmeter
Nacos修改服务权重时报errCode: 500
简介

海边微风起,等风也等你

留言板
留言板
小伙伴们
2Broear Libra の 向往 云帆沧海 若志随笔 豆豆 Chuanbo 诗意笔记
Copyright © 2017-2023 . 皖ICP备17019582号
  • 首页
  • 朝花夕拾
    • 摄影
    • 生活
    • 随笔
  • 编程学习
    • Java
    • Vue
    • WordPress
  • 其它
    • 游记地图
    • 闲言碎语
    • 友情链接
    • 留言板
热门搜索
  • java
  • spring
Stone
75 文章
146 评论
85 喜欢
  • 0
  • 0
  • Top