SpringBoot整合swagger2

• 一、为什么使用swagger2
• 二、swagger2的优点
• 三、swagger中常见的注解
• 四、使用步骤
• • 4.1 maven引入依赖
  • 4.2 创建swagger2的配置类
  • 4.3 实体类
  • 4.4controller
  • 4.5 开启swagger2的注解
  • 4.6 dao、service、mapper没有使用到相关注解不展示
  • 4.7 启动项目，访问
  • • 4.7.1 http://localhost:8080/swagger-ui.html 界面不太友好
    • 4.7.2 http://localhost:8080/doc.html 加了ui依赖才能访问这个

一、为什么使用swagger2

在开发前后端分离的项目时，由于前端和后端的工作由不同的工程师完成。
因此需要后端开发人员编写一份API文档供前端开发人员使用接口。
以前的文档都是后端开发人员手动编写的。
而 Swagger 给我们提供了一个可以根据代码自动生成 API 文档的方式。

二、swagger2的优点

1、代码变，文档变。根据代码自动生成 API 文档。

2、Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。

三、swagger中常见的注解

注解	使用的地方	用途
@Api	类\接口	描述类\接口主要用途
@ApiOperation	用在方法上	描述方法的用途
@ApiImplicitParams	用在方法上	一组参数说明
@ApiImplicitParam	用在@ApiImplicitParams注解中	一个请求参数的各个方面
	name	参数名
	dataType	参数类型
	required	参数是否必须传
	value	参数的意思
	defaultValue	参数默认值
@ApiResponses	用在方法上	返回参数或对象的说明
@ApiResponse	用在@ApiResponses注解中	单个返回参数的说明
@ApiModel	参数实体类	设置接口相关的实体的描述
@ApiModelProperty	参数实体类属性	设置实体属性的相关描述

四、使用步骤

4.1 maven引入依赖

<!--swagger-->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.9.1.RELEASE</version>
        </dependency>
        <!--好看的ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

4.2 创建swagger2的配置类

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket getDocket(){
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("组")
                .apiInfo(apiInfo())
                .select()
                //设置哪些包下的类生产api接口文档
                .apis(RequestHandlerSelectors.basePackage("com.da.demo.controller"))
                //设置哪些请求路径生产接口文档
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo(){
        Contact contact = new Contact("负责人", "url", "邮箱");
        ApiInfo apiInfo=new ApiInfo(
        		"用户管理系统api接口",//title
                "用户管理系统api接口的说明",//description
                "2.0",
                "termsOfServiceUrl",
                contact,
                "Apache 2.0",//license
                "http://www.apache.org/licenses/LICENSE-2.0",//licenseUrl
                new ArrayList<VendorExtension>());
        return apiInfo;
    }
}

4.3 实体类

4.4controller

@Controller
@RequestMapping("/user")
@Api(value = "用户管理的controller",tags = "UserController的API接口")
public class UserController {
    @Autowired
    private UserService userService;
    //restful风格  参数可以请求地址栏的方式传递过来
    @GetMapping("/getAll/{page}/{limit}")
    //@PathVariable 获取请求地址栏上占位符的值
    @ApiOperation(value = "分页查询所有用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page",value = "分页的起始页",required = true,dataType = "Integer"),
            @ApiImplicitParam(name = "limit",value = "每页显示的条数",required = true,dataType = "Integer")
    })
    public String getAll(@PathVariable("page")int p, @PathVariable("limit") int limit, Model model){
        PageInfo pageInfo = userService.selectByPage(p, limit);
        List list = pageInfo.getList();
        Object o = list.get(0);
        model.addAttribute("user", o);
        model.addAttribute("list",list);
        return "hello";
    }
}

4.5 开启swagger2的注解

在springboot启动类或者swagger2配置类 上面添加都可

4.6 dao、service、mapper没有使用到相关注解不展示

4.7 启动项目，访问

4.7.1 http://localhost:8080/swagger-ui.html 界面不太友好

4.7.2 http://localhost:8080/doc.html 加了ui依赖才能访问这个

可以看到接口的详细说明
还可以直接在这里测试接口