zoukankan      html  css  js  c++  java
  • springboot整合swagger

    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;
    
    }
    View Code

    以上两种方式在页面上的结果

     打开看接口详情

     进入测试

     测试结果

     其实swagger还有很多华而不实的功能,如果大家感兴趣可以自己去研究,

    我在这里只是站在生产的角度讲解常用的功能

    如果常用的功能还没有理解到可以看视频演示或者单独问我额!

    完美!

  • 相关阅读:
    SVN 使用锁实现独占式签出
    浏览器console中加入jquery方便调试
    nuget安装说明
    sql server 索引优化
    Windwos Server 2016 远程桌面授权
    tomcat的安装与配置
    业务监控
    敏捷话管理团队
    一键搞定多服务器的更新
    迁移历史sql数据
  • 原文地址:https://www.cnblogs.com/newAndHui/p/14224948.html
Copyright © 2011-2022 走看看