swagger是一个RESTFUL风格的web接口框架 ，主要是为了获取到接口文档 ，这次使用一个项目简单测试一下 ，看看效果

使用步骤：

1：导入依赖：

<!--    接口文档的依赖 -->

    <!--springfox的核心jar包 -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
      <exclusions>
        <exclusion>
          <artifactId>slf4j-api</artifactId>
          <groupId>org.slf4j</groupId>
        </exclusion>
        <exclusion>
          <artifactId>jackson-annotations</artifactId>
          <groupId>com.fasterxml.jackson.core</groupId>
        </exclusion>
        <exclusion>
          <artifactId>spring-aop</artifactId>
          <groupId>org.springframework</groupId>
        </exclusion>
        <exclusion>
          <artifactId>spring-context</artifactId>
          <groupId>org.springframework</groupId>
        </exclusion>
        <exclusion>
          <artifactId>spring-beans</artifactId>
          <groupId>org.springframework</groupId>
        </exclusion>
      </exclusions>
    </dependency>
    <!--springfox-ui的jar包(里面包含了swagger的界面静态文件) -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>

2: springmvc配置文件中配置swagger的放行地址

<!--配置下 swagger 的地址放行-->
    <mvc:resources location="classpath:/META-INF/resources/" mapping="/swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

3:添加swagger的配置类（虽然是配置类 ，最好直接写到controller层中 ）

package com.newcapec.org.controller;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2 //开启 swagger2
@EnableWebMvc//声明是 web 项目
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api(ApiInfo apiInfo) {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
//                .apis(RequestHandlerSelectors.any())
                .apis(RequestHandlerSelectors.basePackage("com.newcapec.org.controller"))
                .build()
                .apiInfo(apiInfo);
    }
    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("卫生监督管理项目Forest接口文档")
                .description("卫生监督管理项目Forest接口测试")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .license("卫生监督管理1.0")
                .licenseUrl("http://127.0.0.1:8888/")
                .build();
    }
}

4:在实体类中的注解配置

@ApiModel(description = "用户数据")
public class Users {
    @ApiModelProperty(value = "用户主键,查询时返回",hidden = true)
    private Integer id;
    @ApiModelProperty(value = "用户名字",required = true,example = "TOM")
    private String username;
    @ApiModelProperty(value = "用户密码",required = true,example = "123")
    private String password;
    @ApiModelProperty(value = "真实名字",required = false,example = "汤姆")
    private String realname;
    private List<Integer> rolesList;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getRealname() {
        return realname;
    }

    public void setRealname(String realname) {
        this.realname = realname;
    }

    public List<Integer> getRolesList() {
        return rolesList;
    }

    public void setRolesList(List<Integer> rolesList) {
        this.rolesList = rolesList;
    }
}

5:在控制器中的注解配置

package com.newcapec.org.controller;

import com.newcapec.org.entity.Users;
import com.newcapec.org.service.UsersService;
import com.newcapec.org.utils.ResponseJson;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpSession;
import java.util.Map;

/**
 * 异步交互技术
 * @RestController = @Controller + @ResponseBody
 *
 * 在异步交互技术的处理器中，所有的返回值为ResponseJson对象
 */
@RestController
@RequestMapping("/users")
@Api(tags = "用户管理模块" )
public class UsersController {

    @Autowired
    private UsersService usersService;

    @PostMapping("/add")
    @ApiOperation("添加用户")
    public ResponseJson add(@RequestBody Users entity){
        usersService.add(entity);
        return ResponseJson.success();
    }

    @PutMapping("/edit")
    @ApiOperation("修改用户")
    public ResponseJson edit(@RequestBody Users entity){
        usersService.edit(entity);
        return ResponseJson.success();
    }

    @DeleteMapping("/remove/{id}")
    @ApiOperation("删除用户")
    public ResponseJson remove(@PathVariable Integer id){
        usersService.remove(id);
        return ResponseJson.success();
    }

    @DeleteMapping("/remove")
    @ApiOperation("批量删除用户")
    public ResponseJson removeBatch(Integer[] id){
        usersService.removeBatch(id);
        return ResponseJson.success();
    }

    @GetMapping("/find/{id}")
    @ApiOperation("通过id查询用户")
    public ResponseJson findById(@PathVariable Integer id){
        Users users = usersService.findById(id);
        return ResponseJson.success(users);
    }

    @GetMapping("/find")
    @ApiOperation("分页查询用户")
    public ResponseJson find(@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
                             @RequestParam(value = "pageSize", defaultValue = "10") Integer pageSize,
                             Users entity){
        Map<String,Object> map = usersService.find(pageNum, pageSize, entity);
        return ResponseJson.success(map);
    }

    @GetMapping("/findAll")
    @ApiOperation("查询所有用户")
    public ResponseJson findAll(){
        return ResponseJson.success(usersService.findAll());
    }

    /**
     * 登录
     * 1.根据用户username查询到单条记录
     * 2.判断用户对象是为null
     * 3.如果为空表示用户名不匹配：给用户提示（响应用户名有误的提示）
     * 4.如果不为空表示用户名匹配：
     * 5.判断密码是否匹配：用户提交的密码与查询到密码进行比对
     * 6.比对成功表示用户登录成功：将用户信息存放在session中
     * 7.比对不成功表示用户提供的密码有误：给用户提示（响应密码有误的提示）
     */
    @PostMapping("/login")
    @ApiOperation("用户登陆")
    public ResponseJson login(String username, String password, HttpSession session){
        Users users = usersService.findByUsername(username);
        if(users == null){
            return ResponseJson.error(501, "用户名有误");
        }
        if(users.getPassword().equals(password)){
            session.setAttribute("loginUser", users);
            return ResponseJson.success();
        }
        return ResponseJson.error(501, "密码有误");
    }

    @GetMapping("/logout")
    @ApiOperation("用户登出")
    public ResponseJson logout(HttpSession session){
        session.removeAttribute("loginUser");
        session.invalidate();
        return ResponseJson.success();
    }

    @GetMapping("/exists")
    @ApiOperation("用户是否存在")
    public Map<String, Object> exists(String username){
        return usersService.exists(username);
    }
}

启动项目 ，直接访问 http://localhost:8888/swagger-ui.html 查看本次项目的接口文档