springboot整合swagger

时间：2021-01-03 21:48:12 阅读：39 评论：0 收藏：0 [点我收藏+]

1.背景

前后端分离后，维护接口文档基本上是必不可少的工作。

一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。

但问题是,现在都是所谓的"敏捷开发",也就是说接口随时要变,这样一来,维护接口文档就成了必不可少的工作了...

别小看维护接口这个工作,做了开发的都明白....虽然不难但是很麻烦的...而且经常维护不及时...

幸好有"丝袜哥"swagger,只需要简单的配置就可以生成接口文档....下面我们隆重的请丝袜哥闪亮登场.....

2.步骤

备注:这里是讲在原来的springboot项目中配置swagger

步骤一:引入jar包

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

View Code

步骤二:WebMvcConfigurer,中排除对swagger的拦截(如果项目中没有拦截器可以不用)

    @Bean
    public FilterRegistrationBean filterRegist() {
        FilterRegistrationBean frBean = new FilterRegistrationBean();
        frBean.setFilter(new HttpServletRequestWrapperFilter());
        frBean.addUrlPatterns("/*");
        frBean.addInitParameter("exclusions", "/api/swagger-resources/**,/api/webjars/**,/api/v2/**,/api/swagger-ui.html/**");
        return frBean;
    }

View Code

步骤三:启动项目然后访问swagger地址:http://localhost:8080/api/swagger-ui.html

界面如下:

技术分享图片

到这里swagger的整合已经完成,

当然这是一个最简单的整合,所有的都是swagger的默认配置,其实swagger还有很多其他的配置,但是我们觉得都是一些华而不实的,几乎用处不大

因为swagger生成的接口文档一般是公司内部使用的,只要能详细知道接口信息就可以了

3.在controller层给接口进行描述

先把controller的代码放上,其他的在详解

package com.ldp.user.controller;

import com.ldp.user.common.annatation.ApiToken;
import com.ldp.user.common.base.BaseResponse;
import com.ldp.user.common.base.ResponseBuilder;
import com.ldp.user.entity.dto.UserSwaggerDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 姿势帝-博客园
 * @address https://www.cnblogs.com/newAndHui/
 * @WeChat 851298348
 * @create 01/03 5:59
 * @description <P>
 * swagger用法展示与测试用
 * </P>
 */
@RestController
@RequestMapping("/test")
@Api(tags = "丝袜哥演示接口") // 接口名称,默认为当前类名 TestSwaggerController
public class TestSwaggerController {
    /**
     * 演示swagger参数没有封装的写法
     *
     * @param username
     * @param weChat
     * @param address
     * @return
     */
    @ApiToken(required = false)
    @PostMapping("/addUser")
    // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写,
    // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....)
    @ApiOperation(value = "添加用户的接口(不封装参数)", notes = "演示swagger参数没有封装的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用")
    // 接口参数描述(选填)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "张无忌", required = true),
            @ApiImplicitParam(name = "weChat", value = "微信", defaultValue = "851298348"),
            @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "光明顶")
    })
    public BaseResponse addUser(@RequestParam(required = true) String username,
                                String weChat,
                                String address) {
        System.out.println("username=" + username);
        System.out.println("weChat=" + weChat);
        System.out.println("address=" + address);
        return ResponseBuilder.success("丝袜哥演示成功");
    }

    /**
     * 演示swagger参数 封装后的写法
     *
     * @param dto
     * @return
     */
    @ApiToken(required = false)
    @PostMapping("/addUser2")
    // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写,
    // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....)
    @ApiOperation(value = "添加用户的接口2(参数使用对象封装)", notes = "演示swagger参数封装后的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用")
    public BaseResponse addUser2(UserSwaggerDTO dto) {
        System.out.println("2 username=" + dto.getUserName());
        System.out.println("2 weChat=" + dto.getWeChat());
        System.out.println("2 address=" + dto.getAddress());
        return ResponseBuilder.success("丝袜哥演示成功2");
    }
}

View Code

方式一:参数没有封装的写法

 /**
     * 演示swagger参数没有封装的写法
     *
     * @param username
     * @param weChat
     * @param address
     * @return
     */
    @ApiToken(required = false)
    @PostMapping("/addUser")
    // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写,
    // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....)
    @ApiOperation(value = "添加用户的接口", notes = "演示swagger参数没有封装的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用")
    // 接口参数描述(选填)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "张无忌", required = true),
            @ApiImplicitParam(name = "weChat", value = "微信", defaultValue = "851298348"),
            @ApiImplicitParam(name = "address", value = "用户地址", defaultValue = "光明顶")
    })
    public BaseResponse addUser(@RequestParam(required = true) String username,
                                String weChat,
                                String address) {
        System.out.println("username=" + username);
        System.out.println("weChat=" + weChat);
        System.out.println("address=" + address);
        return ResponseBuilder.success("丝袜哥演示成功");
    }

View Code

方式二:参数封装成对象的写法

controller接口方法

 /**
     * 演示swagger参数 封装后的写法
     *
     * @param dto
     * @return
     */
    @ApiToken(required = false)
    @PostMapping("/addUser2")
    // 具体接口表示(选填,其实swagger的所有注解都是有默认值的,即可以不写,
    // 而且实际生产也不会写额,因为一般根据接口名字也能知道接口是做什么的.....)
    @ApiOperation(value = "添加用户的接口2", notes = "演示swagger参数封装后的写法,对接口进行详细描述,比如,该接口为新增用户接口,注册时调用")
    public BaseResponse addUser2(UserSwaggerDTO dto) {
        System.out.println("2 username=" + dto.getUserName());
        System.out.println("2 weChat=" + dto.getWeChat());
        System.out.println("2 address=" + dto.getAddress());
        return ResponseBuilder.success("丝袜哥演示成功2");
    }

View Code

接口参数对象

package com.ldp.user.entity.dto;

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

/**
 * @author 姿势帝-博客园
 * @address https://www.cnblogs.com/newAndHui/
 * @WeChat 851298348
 * @create 01/03 6:19
 * @description
 */
@Data
@ApiModel("新增用户参数对象")
public class UserSwaggerDTO {
    @ApiModelProperty(value = "用户名", example = "赵敏", required = true)
    private String userName;

    @ApiModelProperty(value = "微信", example = "851298348")
    private String weChat;

    @ApiModelProperty(value = "地址", example = "峨眉山")
    private String address;

}