swagger集成及使用

Swagger配置

maven引入Swagger依赖

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

创建swagger配置类

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {
}

Tips:一定要放到能被包扫描的位置，swagger会从当前Swagger2.java的位置往下找带有@controller注解的类，进行生成文档

Swagger配置类一般与controller包平齐

配置完成启动项目访问

localhost:8080/项目/swagger-ui.html

效果图
如果出现以上错误，说明项目中缺少相关jackson的依赖
一般前后端分离的项目都会导入该依赖

导入jackson依赖

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.8.7</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.8.7</version>
        </dependency>

再次启动项目

访问localhost:8080/项目/swagger-ui.html

image.png

此时接口文档是空的，因为我们还没有在项目中创建接口

新建Conroller试试Swagger效果

@Controller
public class DemoController {

    @ResponseBody
    @RequestMapping("demo")
    public Object demo(){
        Map<String,String> map = new HashMap();
        map.put("name","张飞");
        return map;
    }
}

重启项目

image.png

可以看到我们新加的demoController
点开demo-controller

image.png
明明只写了一个接口为什么会出现这么多, 仔细看一下接口都是/demo,只是请求方式不同而已,也就说我们在写接口的时候没有限制访问方式，所以所有的请求方式都可以请求到，所以会出现这么多接口,

我们给接口设置只能GET请求访问(效果图如下)

image.png

访问接口

image.png

点击Try it out!发起请求

image.png

请求URL: Request URL
请求头: Request Headers
请求返回的数据: Response Body
请求状态码: Response Code

Swagger常用的注解

注解	位置
@Api(value = "测试Controller",tags = "测试接口")	类上
@ApiOperation(value = "演示接口",notes="详细介绍")	接口上
@ApiParam(name="性别",value="男，女",required=true)	参数

@Api(value = "测试Controller",tags = "测试接口")
@Controller
public class DemoController {

    @ApiOperation(value = "演示接口",notes="详细介绍")
    @ResponseBody
    @RequestMapping(value = "/demo",method = RequestMethod.GET)
    public Object demo(
            @RequestParam(value = "name") String name,
            @RequestParam(value = "age") Integer age,
            @ApiParam(name="性别",value="男，女",required=true) String sex

    ){
        Map<String,Object> map = new HashMap();
        map.put("name",name);
        map.put("age",age);
        map.put("sex",sex);
        return map;
    }
}

以上面的为例看看效果图

image.png

我们看到sex的传参类型是body,如果我们想样传参类型是query此时我们可以用@ApiImplicitParams替代(代码如下)

@Api(value = "测试Controller",tags = "测试接口")
@Controller
public class DemoController {

    @ApiOperation(value = "演示接口",notes="详细介绍")
    @ResponseBody
    @RequestMapping(value = "/demo",method = RequestMethod.GET)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "说明", paramType = "query",required = true),
            @ApiImplicitParam(name = "age", value = "说明", paramType = "query",dataType = "int",required = true),
            @ApiImplicitParam(name = "sex", value = "说明", paramType = "query",required = true)
    })
    public Object demo(
            @RequestParam(value = "name") String name,
            @RequestParam(value = "age") Integer age,
            @RequestParam(value = "sex") String sex
    ){
        Map<String,Object> map = new HashMap();
        map.put("name",name);
        map.put("age",age);
        map.put("sex",sex);
        return map;
    }
}

image.png

保证了接口和生成的文档一致
注解参考链接：https://blog.csdn.net/u014231523/article/details/54411026

最后编辑于：2019.04.02 16:45:06