SpringBoot整合Swagger2文档且在浏览器可以直观的看见

为什么使用Swagger2？

前后端分离后，维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后，接口文档发给前端和后端，大伙按照既定的规则各自开发，开发好了对接上了就可以上线了。当然这是一种非常理想的状态，实际开发中却很少遇到这样的情况，接口总是在不断的变化之中，有变化就要去维护，做过的小伙伴都知道这件事有多么头大！还好，有一些工具可以减轻我们的工作量，Swagger2就是其中之一。

在使用Swagger2 之前所需要的maven依赖

<!--    Swagger 文档功能  start  -->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
 </dependency>
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>
 <!--    Swagger 文档功能    end   -->

当然您可以在这里使用Swagger2 默认的API ，也可以使用自己设计的API；

 @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.nvn.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger")
                        .description("SpringBoot整合Swagger，详细信息......")
                        .version("9.0")
                        .contact(new Contact("啊啊啊啊","blog.csdn.net","aaa@gmail.com"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }

使用自己定义的API在浏览器上浏览的效果图：http://localhost:9999/swagger-ui.html

使用默认的API效果图：

Swagger2 注解

1. @Api注解可以用来标记当前Controller的功能。
2. @ApiOperation注解用来标记一个方法的作用。
3. @ApiImplicitParam注解用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
4. 如果有多个参数，则需要使用多个@ApiImplicitParam注解来描述，多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。
5. 需要注意的是，@ApiImplicitParam注解中虽然可以指定参数是必填的，但是却不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架内必填，抛弃了Swagger2，这个限制就没用了，所以假如开发者需要指定一个参数必填，@RequestParam(required = true)注解还是不能省略

package com.ytzl.demo.controller;

import com.ytzl.demo.entity.Person;
import com.ytzl.demo.entity.StudentEntity;
import com.ytzl.demo.entity.TeacherEntity;
import com.ytzl.demo.entity.UserEntity;
import com.ytzl.demo.util.R;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.*;

/**
 * @ClassName: HelloSpringBootController
 * @Author: Lcy
 * @Date: 2020/8/17 10:33
 * @since SDK 1.9
 */
@Api(value = "HelloSpring Boot",tags = {"欢迎Spring Boot"})
@RestController
public class HelloSpringBootController {

    @RequestMapping("/hello")
    @ApiOperation("这是一个简单的返回数据类型")
    public String sayHello() {
        return "Hello SpringBoot";
    }

    //  返回List数据
    @RequestMapping("/list1")
    @ApiOperation("返回List数据")
    public List list1() {
        List<Integer> list = new ArrayList<Integer>();
        list.add(1);
        list.add(2);
        list.add(3);
        return list;
    }

    // 返回Set数据的
    @RequestMapping("/set")
    @ApiOperation("返回Set数据")
    public HashSet Set1() {
        HashSet set = new HashSet();
        set.add(1);
        set.add(2);
        set.add(3);
        set.add(4);
        return set;
    }

    // 返回Map数据
    @RequestMapping("/map")
    @ApiOperation("返回Map数据")
    public Map<String, String> Map1() {
        Map<String, String> map = new HashMap();
        map.put("a", "1");
        map.put("b", "2");
        map.put("c", "3");
        return map;
    }


    // 返回List<UserEntity>
    @RequestMapping("/userTest")
    @ApiOperation("使用List返回用户数据")
    public List<UserEntity> userTest() {
        List<UserEntity> userList = new ArrayList<UserEntity>();
        userList.add(new UserEntity("张三", 12, "男"));
        userList.add(new UserEntity("李四", 34, "男"));
        userList.add(new UserEntity("琳琳", 11, "女"));
        return userList;
    }

    //  返回Set<StudentEntity>
    @RequestMapping("/studentTest")
    @ApiOperation("使用Set返回用户数据")
    public Set<StudentEntity> studentTest() {
        Set<StudentEntity> studentEntities = new HashSet<StudentEntity>();
        studentEntities.add(new StudentEntity("张三", "3"));
        studentEntities.add(new StudentEntity("李四", "2"));
        studentEntities.add(new StudentEntity("吴兰", "1"));
        return studentEntities;
    }
    
    @RequestMapping("/studentMap")
    @ApiOperation("返回用户数据")
    public Map<String, StudentEntity> mapTest() {
        Map<String, StudentEntity> studentEntityMap = new HashMap<String, StudentEntity>();
        studentEntityMap.put("1", new StudentEntity("张三", "1"));
        studentEntityMap.put("2", new StudentEntity("无敌", "2"));
        studentEntityMap.put("3", new StudentEntity("天秀", "3"));
        return studentEntityMap;
    }

    @RequestMapping("/ss")
    @ApiOperation("返回学生数据")
    public Set<StudentEntity> studentEntitySet() {
        HashSet<StudentEntity> entities = new HashSet<StudentEntity>();
        entities.add(new StudentEntity("吴兰", "123"));
        entities.add(new StudentEntity("天猫", "234"));
        entities.add(new StudentEntity("晚霜", "565"));
        entities.add(new StudentEntity("琳琳", "676"));
        return entities;
    }

    @RequestMapping("/sayParam")
    @ApiOperation("返回姓名")
    @ApiImplicitParam(name = "str",value="名称",required = true)
    public String sayParam(@RequestParam("str") String name) {
        return name;
    }

    @RequestMapping("returnUser")  
    @ApiOperation("返回json格式的用户")
    public R returnUser() {
        UserEntity userEntity = new UserEntity();
        userEntity.setUserAge(23);
        userEntity.setUserName("李四");
        return new R(0, "返回成功", userEntity);
    }

    @RequestMapping("returnUserList")
    @ApiOperation("使用List返回json格式的用户")
    public R returnUserList() {
        List<UserEntity> userEntityList = new ArrayList<UserEntity>();

        UserEntity userEntity = new UserEntity();
        userEntity.setUserName("无锡");
        userEntity.setUserAge(34);

        UserEntity userEntity1 = new UserEntity();
        userEntity1.setUserAge(45);
        userEntity1.setUserName("天天");

        userEntityList.add(userEntity);
        userEntityList.add(userEntity1);

        return R.success(0, "操作成功，有权限访问", userEntityList);
    }

    @RequestMapping("returnR")
    @ApiOperation("返回json格式的用户")
    public R returnR() {
        UserEntity userEntity = new UserEntity();
        userEntity.setUserName("张三");
        userEntity.setUserAge(23);
        return R.success(userEntity);
    }

    @Autowired
    private TeacherEntity teacherEntity;

    @RequestMapping("getTeacherInfo")
    public R returnTeacher() {
        return R.success(teacherEntity);
    }

    @Autowired
    private Person person;

    @RequestMapping("person")
    public R returnPerson() {
        return R.success(person);
    }

}