springboot整合swagger demo

 

项目地址链接:

文章底部

前言

 现在的开发基本上都是前后端分离，前后端交互都是通过API文档。有了API文档大家各自开发，互不干扰。

1、传统方式

传统方式是文档设计好之后，分别发给前端和后端人员。这样有个缺点，接口信息一旦变化，文档就需要重新发送给前后端人员。无法做到实时。所以浪费时间和精力。

2、swagger方式

我们的后台应用集成了swagger之后，会自动暴露出我们的接口，而且这个接口形式还是通过restful风格发布的。一旦后端的接口有变化，会立刻显示出来，因此极大地提高了效率。

OK，基本上一句话就可以总结他的好处，那就是后端写的api文档可以通过swagger的形式实时的发布出来，供前端人员查看。

添加依赖

<!--swagger2 依赖-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<!--swagger-ui 依赖 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

SwaggerConfig

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题: xiao pan_接口文档")
                // 描述
                .description("描述: 用于管理xxx项目, xxx模块")
                // 作者信息
                .contact(new Contact("xiao pan","https://blog.csdn.net/weixin_43652507?type=blog","xxx@163.com"))
                .version("版本号: 1.0.0")
                .build();
    }
}

UserController

import com.example.swaggerdemo.domain.User;
import com.example.swaggerdemo.exception.MyException;
import com.example.swaggerdemo.response.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;


@Api(value = "用户接口", tags = {"用户接口"})
@RestController
public class UserController {


    @ApiOperation("查询用户列表")
    @GetMapping("/list")
    public ResponseResult list(){
        ArrayList<User> list = new ArrayList<>();
        User user = new User();
        user.setId(1);
        user.setName("张三");
        user.setAge(18);
        User user2 = new User();
        user2.setId(2);
        user2.setName("李四");
        user2.setAge(28);
        list.add(user);
        list.add(user2);
        return ResponseResult.createBySuccess(list);
    }

    @ApiOperation(value = "根据用户id查询",notes = "只查询id=1的用户")
    @GetMapping("/selectByUserId")
    public ResponseResult selectByUserId(Integer userId){
        if (userId == null) {
            throw new MyException("用户id不能为空");
        }
        if (userId!=1) {
            throw new MyException("只查询1的用户");
        }
        User user = new User();
        user.setId(1);
        user.setName("张三");
        user.setAge(18);
        return ResponseResult.createBySuccess(user);
    }

    @ApiOperation(value = "更新用户信息",notes = "请输入id,name,age的值")
    @PostMapping("/update")
    public ResponseResult update(User user){
        if (user == null || user.getId()==null || StringUtils.isEmpty(user.getName()) || user.getAge()==null) {
            throw new MyException("请输入id,name,age的值");
        }
        return ResponseResult.createBySuccess(user);
    }

    @ApiOperation(value = "根据用户id删除")
    @DeleteMapping("/delete")
    public ResponseResult delete(Integer userId){
        if (userId==null) {
            throw new MyException("用户id不能为空");
        }
        return ResponseResult.createBySuccess("操作成功");
    }
}

访问地址：http://项目实际地址/swagger-ui.html

项目地址链接:

https://gitee.com/PanGuanQing/swagger-demo.git