swagger使用

依赖

        <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>

配置

package com.study.swagger.config;


import io.swagger.annotations.Api;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * @author: 李坡
 * @date: 2019/1/17 10:08
 */
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token")
                .description("令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("query")
                .required(false);
        pars.add(tokenPar.build());

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //.apis(RequestHandlerSelectors.basePackage("com.sst"))
                // 这里是全局扫描有@Api注解得类，还可以扫描任意位置，指定包以及针对方法上的指定注解
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("个人测试")
                .description("个人测试用api")
                .termsOfServiceUrl("")
                .contact("测试")
                .version("1.0")
                .build();
    }
}

controller

package com.study.swagger.controller;

import com.study.swagger.model.BaseForm;
import com.study.swagger.model.GetForm;
import com.study.swagger.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author: 李坡
 * @date: 2019/1/17 12:00
 */
@RestController
@RequestMapping("/user")
@Api(value = "用户Controller", tags = {"用户", "测试", "Controller"})
public class UserController {

    @ApiOperation(value = "查询用户", notes = "查询用户", httpMethod = "POST")
    @RequestMapping(value = "/getByForm")
    //返回值不能是Object，否则，swagger返回不显示。
    //Result具体化泛型，swagger就显示具体类
    //swagger根据方法的返回值显示，与具体的返回结果无关
    public Result<PageVO<User>> getByForm(GetForm form){
        User u = new User(form.getName(), form.getAge());
        List<User> list = new ArrayList<>();
        list.add(u);
        //return Result.ok(u);//swagger显示
        //return Result.ok(list);//swagger也显示
        PageVO<User> pageVO = new PageVO<>(10, list);
        return Result.ok(pageVO);//swagger也显示。
    }

}

实体类
入参

package com.study.swagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.util.List;

/**
 * 基础表单.
 *
 * @author <a href="mailto:simonzbf@163.com">大兵</a>
 * @version 1.0 18/4/24
 * @since 1.0
 */
@Data
@ApiModel//只需要子类添加这个注解，父类不需要添加这个注解
public class GetForm extends BaseForm {
    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;

}

@Data
public class BaseForm {

    @ApiModelProperty("请求id")
    private String requestId;

    private Boolean excel;

}

返回

package com.study.swagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * Created by e-lipo on 2019/4/2.
 */
@Data
@ApiModel
@AllArgsConstructor
@NoArgsConstructor
public class User {
    @ApiModelProperty("姓名")
    private String name;

    @ApiModelProperty("年龄")
    private Integer age;
}

package com.study.swagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * @author zhangqi
 * @date 2019/3/25 8:54 AM
 */
@Data
@NoArgsConstructor
@ApiModel
public class Result<T> implements Serializable {

    @ApiModelProperty("数据")
    T data;

    @ApiModelProperty("提示信息")
    String message;

    @ApiModelProperty("状态码")
    Integer code;
    
    public Result(Integer code, String message){
        this.code = code;
        this.message = message;
    }

    public Result(Integer code, String message, T data){
        this.data = data;
        this.code = code;
        this.message = message;
    }

    public static <T> Result ok(T data){
        return new Result(0, "成功", data);
    }

}

package com.study.swagger.model;

import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.util.List;

/**
 * Created by e-lipo on 2019/4/2.
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
public class PageVO<T> {
    @ApiModelProperty("总记录数")
    private long total;

    @ApiModelProperty("数据集合")
    private List<T> list;
}

启动成功后，访问
http://localhost:8080/swagger-ui.html