springboot学习(二):使用Swagger2构建RESTful API

说明

在第一次学习本节内容时，没有很重视只是走了遍流程，当学到springcloud微服务，众多微服务的API文档都分散在各自的服务中，如何聚集到一起，就需要通过Swagger2在网关中聚集，在此回顾下当初springboot中Swagger2的用法。

正文

构建springboot项目，引入依赖包，这里我使用放在本地的tomcat启动，所以也引入了web依赖

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
            <scope>compile</scope>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
 </dependencies>

引入依赖后需要创建一个配置类，该类可以放在与Application类同级，可以放在自创的config包中，这里放在config包中

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket creatRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller")) //扫描该包下所有的controller
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger RESTful APIs ")  //API文档标题
                .description("学习swagger构建restful api") // 文档描述
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

配置好之后，创建controller为具体方法添加描述

@RestController("/test")
public class TestController {

    @ApiOperation(value = "hello",notes = "输出hello world")
    @RequestMapping("/hello")
    public String hello(){
        return "hello world";
    }

    @ApiOperation(value = "list",notes = "查询相关内容")
    @GetMapping("list")
    public String add(){
        return "list";
    }

    @ApiOperation(value = "update",notes = "更新相关内容")
    @ApiImplicitParam(name = "params",value = "更新的内容",required = true,dataType = "String")
    @PostMapping("update")
    public String update(String params){
        return "update";
    }

    @ApiOperation(value = "delete", notes = "删除相关内容")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,dataType = "String")
    @PostMapping("delete{id}")
    public String delete(@PathVariable String id){
        return "delete";
    }

}

启动tomcat，访问http://localhost:8081/swagger/swagger-ui.html#/，可以看到

通过API文档可以看到，当hello方法没有指定具体的HTTP请求方法类型时，文档会自动创建所有类型的api

点击try it out 进行测试

源码地址：https://github.com/Edenwds/springboot_study/tree/master/swagger

参考：http://blog.didispace.com/springbootswagger2/