倪升武的博客

这世上天才很少,懒蛋却很多,你若对得起时间,时间便对得起你!

SpringBoot集成Swagger2展现在线接口文档

原文链接:http://blog.itcodai.com/blog/20
之前由于太忙了,一直没发博客,也比较少上CSDN了,博客中很多朋友有留言也没有好好回复,非常抱歉~~后面会继续发博客的,争取每周最少一篇~主要是发springboot和springcloud的相关博客吧,现在开发也在用这些,顺便整理些点出来,总结总结,我自己也在搭建一个个人博客,等备案好了就上上去,是用springboot搞的,到时候也把源码发出来,一起交流~这篇博客主要总结一下Swagger的在springboot中的集成。

1. Swagger简介

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了前后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,Swagger就是一款让你更好的书写API文档的框架。
后端开发人员在开发的过程中,可以使用Swagger来调试接口,给开发提供便利。

更多信息可参考Swagger官方文档

2. 工具与环境

  • 开发工具:IntelliJ IDEA
  • JDK版本:1.8
  • SpringBoot版本:2.0.1 RELEASE
  • Swagger版本:2.8.0

3. maven依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

4. Swagger配置

新建一个配置类,需要添加@EnableSwagger2注解。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author shengwu ni
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger测试接口")
                .description("demo")
                .termsOfServiceUrl("http://www.5icodai.com/")
                .version("1.0")
                .build();
    }
}

到此可以看一下页面效果,在浏览器中输入localhost:8080/swagger-ui.html,即可看到swagger接口页面,如下图所示,说明Swagger2集成成功。

img

【友情提示】如果遇到下面的页面,而且还关不掉的,是因为浏览器缓存引起的,清空一下浏览器缓存即可解决。

img

5. 测试一下

下面在controller中写几个接口测试一下,顺便介绍一下Swagger中的几个常用的注解。

5.1 测试实体类

写一个User实体类作为测试对象,省略了set和get方法。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户实体")
public class User {

    @ApiModelProperty(value = "主键id")
    private Long id;
    @ApiModelProperty(value = "用户姓名")
    private String username;
    @ApiModelProperty(value = "用户密码")
    private String password;

    // 省略set和get方法
}

@ApiModel注解用于实体类,表示对类进行说明,用于参数用实体类接收。
@ApiModelProperty用于字段,表示对model属性的说明或者数据操作更改。

5.2 测试controller

写一个SwaggerTestController来测试一下,再结合Swagger页面来感受一下Swagger的强大之处。

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

/**
 * Swagger测试controller
 * @author shengwu ni
 */
@RestController
@Api(tags = "Swagger功能测试接口")
@RequestMapping("/test")
public class SwaggerTestController {

    @GetMapping("/get/{id}")
    @ApiOperation(value = "查询用户信息", notes = "查询用户信息")
    public User getUser(@PathVariable Long id) {
        // 这里就不查了
        User user = new User();
        user.setId(id);
        user.setUsername("倪升武");
        user.setPassword("123456");
        return user;
    }

    @PutMapping("/update")
    @ApiOperation(value = "更新用户信息", notes = "更新用户信息")
    public void updateUser(@RequestBody User u) {
        // 这里就不更新了
        User user = new User();
        user.setId(u.getId());
        user.setUsername(u.getUsername());
        user.setPassword(u.getPassword());
    }

    @PostMapping("/add")
    @ApiOperation(value = "添加用户信息", notes = "添加用户信息")
    public void addUser(@RequestBody User u) {
        User user = new User();
        user.setId(u.getId());
        user.setUsername(u.getUsername());
        user.setPassword(u.getPassword());
    }

    @DeleteMapping("/delete")
    @ApiOperation(value = "删除用户信息", notes = "删除用户信息")
    public void deleteUser(@RequestParam Long id) {
        System.out.println("删除用户信息,id为: " + id);
    }
}

@Api用于类,表示标识这个类是swagger的资源。
@ApiOperation用于方法,表示一个http请求的操作。

以上四个注解是Swagger中常用的,接下来运行一下项目工程,看一下下图页面的展示的四个接口状态。

img
可以看出,swagger中将四个接口的url以及备注的功能信息都列出来了,很直观,可以直接在该页面测试这些接口返回的数据是否正常,已查询用户信息为例看一下返回的json效果。

img

Swagger以json的格式将数据展示出来。SpringBoot集成Swagger2就介绍这么多。

阅读更多
版权声明:尊重博主原创文章,转载请注明出处 https://blog.csdn.net/eson_15/article/details/80503205
文章标签: SpringBoot
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭