Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单.

添加库

        <!--swagger集成，接口测试-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox.version}</version>
        </dependency>

配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //设置是否生成文档
    @Value("${swagger.show}")
    private boolean swaggerShow;

    /**
     * 可以定义多个组，比如本类中定义把test和demo区分开了 （访问页面就可以看到效果了）
     */
    @Bean
    public Docket testApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(this.swaggerShow)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.api"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API")
                .description("××管理系统api")
                .termsOfServiceUrl("http://example.eric.com")
                .contact("eric")
                .version("1.0")
                .build();
    }
}

代码注解

• 接口注解

package com.wangheart.boot.user;

import com.wangheart.boot.entity.LoginRequest;
import com.wangheart.boot.entity.Result;
import com.wangheart.boot.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * Author : eric
 * CreateDate : 2017/5/5  18:47
 * Email : ericli_wang@163.com
 * Version : 2.0
 * Desc :
 * Modified :
 */
@RestController
@RequestMapping("/user")
@Api(value = "用户", tags = "用户接口")
public class UserController {
    private final static Logger logger = LoggerFactory.getLogger(UserController.class);

    @ApiOperation(value = "登录")
    @RequestMapping(value = "login", method = RequestMethod.POST)
    public Result login(@RequestBody LoginRequest loginRequest) {
        Result result = new Result<>();
        result.setDatas(new User());
        return result;
    }

    @ApiOperation(value = "查询用户详情")
    @ApiImplicitParam(name = "id", value = "用户id", paramType = "path", dataType = "string", required = true)
    @RequestMapping(value = "info/{id}", method = RequestMethod.GET)
    public Result<User> getUserInfo(@PathVariable String id) {
        Result<User> result = new Result<>();
        result.setDatas(new User());
        return result;
    }

    @ApiOperation(value = "条件查询用户")
    @RequestMapping(value = "list", method = RequestMethod.GET)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "startTime", value = "开始时间", paramType = "form", dataType = "string", required = true),
            @ApiImplicitParam(name = "endTime", value = "结束时间", paramType = "form", dataType = "string", required = true),
            @ApiImplicitParam(name = "pageSize", value = "每页数量", paramType = "form", dataType = "int", required = true),
            @ApiImplicitParam(name = "pageNum", value = "页码", paramType = "form", dataType = "int", required = true)})
    public Result<List<User>> getUserList(@RequestParam String startTime,
                                          @RequestParam String endTime,
                                          @RequestParam int pageSize,
                                          @RequestParam int pageNum) {
        Result<List<User>> result = new Result<>();
        List<User> list = new ArrayList<>();
        list.add(new User());
        result.setDatas(list);
        return result;
    }
}

• 实体注解

  @Data
  public class User{
      @ApiModelProperty(value = "用户id", example = "11111")
      private String id;
      @ApiModelProperty(value = "登录账号", example = "13249861111")
      private String account;
      @JSONField(serialize = false)
      private String password;
      @ApiModelProperty(value = "昵称", example = "张三")
      private String nickName;
  }
  

swagger1.png

swagger2.png

swagger3.png

swagger4.png

​