Swagger™的目标是为REST APIs 定义一个标准的,与语言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过Swagger定义,消费者就能与远程的服务互动通过少量的实现逻辑。类似于低级编程接口,Swagger去掉了调用服务时的很多猜测。

Swagger的配置还是稍微有些复杂,为了简化其实现方式,我们直接适用Starter进行配置。
https://github.com/SpringForAll/spring-boot-starter-swagger

pom引入

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.1.RELEASE</version>
</dependency>

注解

在应用主类中增加@EnableSwagger2Doc注解

@EnableSwagger2Doc
@SpringBootApplication
public class Bootstrap {

    public static void main(String[] args) {
        SpringApplication.run(Bootstrap.class, args);
    }

}

配置

swagger.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
swagger.contact.email=dyc87112@qq.com
swagger.base-package=com.didispace
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

然后启动即可

访问路径

http://<host>:<port>/swagger-ui.html

注解说明

@Api

用在类上,说明该类的作用

比如说:@Api(value = “UserController”, description = “用户相关api”)

@Api(value="物料")
@Controller
@RequestMapping("material")
public class MaterialController {
   @Resource
    protected MaterialService materialService;
    @ApiOperation(httpMethod="POST", value="创建物料")
    @RequestMapping("service/create")
    @ResponseBody
    public ResponseResult<String> create(@RequestBody Material material) {
    }
}

@ApiOperation

用在方法上,说明方法的作用

比如说:

@ApiOperation(value = “查找用户”, notes = “查找用户”, httpMethod = “GET”, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    @ApiOperation(httpMethod="POST", value="查询物料")
    @RequestMapping("service/findByPage")
    @ResponseBody
    public ResponseResult<PageView<Material>> findByPage(
@ApiParam(value="所在页",defaultValue="0")
@RequestParam(defaultValue="0") int pageNo,
@ApiParam(value="每页数量",defaultValue="10")
@RequestParam(defaultValue="10") int pageSize,
@ApiParam(value="查询条件,属性名请参考 Material")
@RequestBody(required=false) List<QueryParam> params) {
    }

@ApiImplicitParams

用在方法上包含一组参数说明
paramType:参数放在哪个地方
header–>请求参数的获取:@RequestHeader
query–>请求参数的获取:@RequestParam
path(用于restful接口)–>请求参数的获取:@PathVariable
body(不常用)
form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传
value:参数的意思
defaultValue:参数的默认值

比如说:

@ApiOperation(httpMethod = "GET", value = "获取店铺列表", response = ResponseResult.class,
    notes = "实现方式可以用get请求,直接传当前页以及页码大小以及排序等:http://localhost:8888/shop/find?sort=cellphone,asc&sort=shopFullName,desc&page=1&size=10")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "province",required = false, value = "省",paramType ="query", dataType = "String"),
        @ApiImplicitParam(name = "city",required = false, value = "市",paramType ="query", dataType = "String"),
        @ApiImplicitParam(name = "county",required = false, value = "县",paramType ="query", dataType = "String"),
        @ApiImplicitParam(name = "pageable",required = false, value = "分页,排序对象",paramType ="body", dataType = "Pageable")
    })
    @ResponseBody
    @RequestMapping(value = { "/findAll" }, method = { RequestMethod.GET, RequestMethod.POST })
    public ResponseResult<Page<ShopInfo>> findAll(
            @RequestParam(required = false) String province,
            @RequestParam(required = false) String city,
            @RequestParam(required = false) String county,
            @PageableDefault(sort = { "id" }, direction = Sort.Direction.ASC) Pageable pageable) {
        return ResponseResult.success(shopList);
    }

@ApiResponses

@ApiResponses用于表示一组响应

@ApiResponse

@ApiModel

描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModel(value = “用户实体类”)

@ApiModel(value = "优惠劵信息")
@Entity
@Table(name = "coupon_info")
public class CouponInfo implements Serializable {

}

@ApiModelProperty

描述一个model的属性
@ApiModelProperty(value = “登录用户”)

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;
import java.util.Date;

@ApiModel(value="物料")
public class Material implements Serializable {

    @ApiModelProperty("主键")
    private String id;

    @ApiModelProperty("项目ID")
    private String projectId;

    @ApiModelProperty("公司Id")
    private String companyId;
    //get,set
}