Osheep

时光不回头,当下最重要。

springboot-swagger

springboot-swagger

首先说下swagger是个什么东西。

Swagger是一种Rest API的 简单但强大的表示方式,标准的,语言无关,这种 表示方式不但人可读,而且机器可读。 可以作为Rest API的交互式文档,也可以作为Rest API的形式化的接口描述,生成客户端和服务端的代码

官网地址:https://swagger.io/

我的理解swagger就是一个基于接口和文档于一体的玩意

  • 首先,下载swagger相关的依赖
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.2.2</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.2.2</version>
</dependency>   
  • 其次,在启动方法添加相关的注解
@SpringBootApplication
// 这个注解必须的
@EnableSwagger2
@ComponentScan("com.yuxi")
@MapperScan("com.yuxi.dao")
public class SpringBootMain {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootMain.class, args);
    }
}

好了是不是很神奇,就可以了你可以直接访问:localhost:8888/swagger-ui.html

当然这个确实是好了,不过这样的api接口文档也太简陋了,参数也m没有说明,谁知道你写的什么意思呢?

接下来我们就看看swagger给我们提供的一系列的注解参数

  • 最后,swagger注解说明
    @Api:用在类上,说明该类的作用
    @ApiOperation:用在方法上,说明方法的作用
    @ApiImplicitParams:用在方法上包含一组参数说明
    @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    paramType:参数放在哪个地方
    header–>请求参数的获取:@RequestHeader
    query–>请求参数的获取:@RequestParam
    path(用于restful接口)–>请求参数的获取:@PathVariable
    body(不常用)
    form(不常用)
    name:参数名
    dataType:参数类型
    required:参数是否必须传
    value:参数的意思
    defaultValue:参数的默认值
    @ApiResponses:用于表示一组响应
    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
    code:数字,例如400
    message:信息,例如”请求参数没填好”
    response:抛出异常的类
    @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiModelProperty:描述一个model的属性

当然这些注解是我参考的,参考文章为:http://www.cnblogs.com/java-zhao/p/5348113.html

这个是我使用注解的代码块:

    @ApiOperation("根据账单ID查询")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "id", value = "订单ID",  dataType = "int")
    })
    @RequestMapping(value = "/{id}", method = RequestMethod.GET)
    @ApiResponses(value = {
            @ApiResponse(code = 401, message = "参数错误"),
            @ApiResponse(code = 404, message = "路径不正确"),
            @ApiResponse(code = 501, message = "内部错误"),
            @ApiResponse(code = 200, message = "正常返回")
    })
   public Account getAccountById(@PathVariable("id") int id) {
            return accountService.findAccountById(id);
   }

想看更多源码地址请参考:
http://git.oschina.net/xiaoyuxi/springbootlearning

点赞