swagger初探

最近换了新团队，之前都是使用rap作为接口管理工具，个人感觉还是挺好用的。新团队是全部spring cloud的架构，准备开始学习使用swagger作为管理平台。swaggerHub看起来也是融合了多种工具，包括swagger editor, swagger ui, swagger codegen。本来是想用swagger editor（与rap功能类似）用来编辑接口文档的，奈何网络环境问题，无法安装。就先研究了下swagger ui。

一. 添加依赖

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.6.1</version>
    </dependency>

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.6.1</version>
    </dependency>

第二种配置方式,好像需要spring-boot版本要高于2.0以上（未深入研究，不是十分确定）

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

二.配置和加注解

@Configuration
@EnableSwagger2 // 启用 Swagger
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().enable(true);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("部门列表请求")
                .version("1.0")
                .build();
    }
}

三. 配置api接口

@Api和@ApiOperation(value = “获取部门信息”) 都是

@Api(value = "部门管理")
@RestController
@RequestMapping(value = "/dept")
public class DeptController {
    private DeptService deptService;

    @Autowired
    public void setDeptService(DeptService deptService) {
        this.deptService = deptService;
    }


    @ApiOperation(value = "获取部门信息")
    @GetMapping("get/{id}")
    public Dept getDept(@PathVariable int id) {
        return deptService.get(id);
    }

    @ApiOperation(value = "获取部门列表")
    @GetMapping("list/")
    public List<Dept> getList() {
        return deptService.getList();
    }

    @ApiOperation(value = "添加部门")
    @PostMapping("addDept/")
    public void addDept(Dept dept) {
        deptService.addDept(dept);
    }
}

四. 运行，访问

启动项目，访问地址localhost:port/swagger-ui.html,就能看到如下页面,看起来很清晰，可以增加接口描述等各类信息，还可以mock。唯一不足之处需要启动服务之后，才可以访问，并且是写完代码之后才会生成。不适用于提前确定接口报文。我感觉其作用更多的是对现有接口的文档维护。而想要和前端约定报文的话，可以使用swagger editor。有机会的话，我再研究研究。

五.附录

附上一些api介绍：

 @Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。
参数：
 ·paramType：指定参数放在哪个地方
    ··header：请求参数放置于Request Header，使用@RequestHeader获取
    ··query：请求参数放置于请求地址，使用@RequestParam获取
    ··path：（用于restful接口）-->请求参数的获取：@PathVariable
    ··body：（不常用）
    ··form（不常用）
 ·name：参数名
 ·dataType：参数类型
 ·required：参数是否必须传(true | false)
 ·value：说明参数的意思
 ·defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    ——code：数字，例如400
    ——message：信息，例如"请求参数异常!"
    ——response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

@ApiModelProperty：描述一个model的属性