springBoot整合Swagger2，搭建Restful API 在线文档

目录

1引入依赖

2配置Swagger2

3写生成文档的注解 

4示例代码

---

Swagger2是一个功能强大的在线API文档框架，Swagger2提供了在线文档的查阅和测试功能。

1引入依赖

在pom文件中引入依赖

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

2配置Swagger2

写一个配置类Swagger2,在类的上方加上@Configuration注解，表明是一个配置类，加上@EnableSwagger2开启Swagger2的功能，在Swagger2中需要注入一个Docket的bean,改bean包含了基本的API文档描述信息，以及包扫描的基本包名等信息，代码如下

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.forezp.helloworld.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().title("springBoot 使用 Swagger2构建API文档")
                .description("简单优雅的rest风格")
                .termsOfServiceUrl("http://www.baidu.com")
                .version("1.0")
                .build();
    }
}

3写生成文档的注解 

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。 tags="说明该类的作用"

@ApiOperation："用在请求的方法上，说明方法的作用" value="说明方法的作用" notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
    @ApiImplicitParam：对单个参数的说明        
        name：参数名
        value：参数的说明、描述
        required：参数是否必须必填
        paramType：参数放在哪个地方
            · query --> 请求参数的获取：@RequestParam
            · header --> 请求参数的获取：@RequestHeader          
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（请求体）-->  @RequestBody User user
            · form（普通表单提交）       
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

@ApiResponses：方法返回对象的说明

    @ApiResponse：每个参数的说明 code：数字，例如400 message：信息，例如"请求参数没填好"

4示例代码

import com.forezp.helloworld.service.UserService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
@RequestMapping("/user")
@RestController
@Api(tags = "用户管理模块")
public class UserController {
    @Autowired
    UserService userService;
    @ApiOperation(value = "根据姓名查询用户",notes = "查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "用户姓名",required = true,paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/queryByName",method = RequestMethod.GET)
    public String query(String name){
        return userService.queryByName(name);
    }

    @ApiOperation(value = "新增修改用户",notes = "新增修改用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,paramType = "query")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/addOrUpdate",method = RequestMethod.POST)
    public String addOrUpdate(@RequestParam("id") String id){
        return userService.addOrUpdate(id);
    }


    @ApiOperation(value = "根据用户id删除用户",notes = "删除用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",required = true,paramType = "path")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @RequestMapping(value = "/deleteByID/{id}",method=RequestMethod.POST)
    public String deleteByID(@PathVariable("id") String id){
        return userService.deleteByID(id);
    }
}

启动功能在浏览器上访问http://localhost:8080/swagger-ui.html