idea SpringBoot项目 swagger全新讲解及其相应swagger Api

1.pom.xml文件中引入依赖

   io.springfox
   springfox-swagger2
   2.6.1



   io.springfox
   springfox-swagger-ui
   2.6.1

2.Swagger2启动类

package com.springdir.springdir;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.springdir.springdir"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建Restful Api")
                .description("更多Spring Boot相关文章请关注：http://www.baidu.com/")
                .termsOfServiceUrl("http://www.baidu.com/")
                .contact("Liangdq")
                .version("1.0")
                .build();
    }
}

3.Controller接受相应的参数形式

@ApiOperation
@ApiImplicitParam
@ApiImplicitParams
用于描述创建的api

package com.springdir.springdir.web;

import com.springdir.springdir.entity.Area;
import com.springdir.springdir.service.AreaService;
import com.springdir.springdir.utils.FormatResponseUtil;
import com.springdir.springdir.utils.ResponseResult;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/area")
public class AreaController {

    @Autowired
    private AreaService areaService;

    @ApiOperation(value="获取区域列表", notes="")
    @GetMapping("/arealist")
    public ResponseResult queryAreaAll(){
        return FormatResponseUtil.formatResponse(areaService.queryAll());
    }

    @ApiOperation(value="获取区域详细信息", notes="根据url的id来获取区域详细信息")
    @ApiImplicitParam(name = "id", value = "区域ID", required = true, dataType = "int"  , paramType =  "query")
    @GetMapping("/one")
    public ResponseResult queryAreaById(@RequestParam("id") int id){
        return FormatResponseUtil.formatResponse(areaService.queryAreaById(id));
    }

    @ApiOperation(value="创建区域信息", notes="根据Area对象创建用户")
    @ApiImplicitParam(name = "area", value = "区域实体Area", required = true, dataType = "Area")
    @PostMapping("/addarea")
    public ResponseResult addArea(@RequestBody Area area){
        return  FormatResponseUtil.formatResponse(areaService.addArea(area));
    }

    @ApiOperation(value="更新区域详细信息", notes="根据url的id来指定更新对象，并根据传过来的area信息来更新用户详细信息")
//    @ApiImplicitParams({
//            @ApiImplicitParam(name = "id", value = "区域ID", required = true, dataType = "int"),
//            @ApiImplicitParam(name = "area", value = "区域实体Area", required = true, dataType = "Area")
//    })
    @ApiImplicitParam(name = "area", value = "区域实体Area", required = true, dataType = "Area")
    @PostMapping("/updateinfo")
    public ResponseResult updateInfo(@RequestBody Area area){
        return FormatResponseUtil.formatResponse(areaService.updateArea(area));
    }

    @ApiOperation(value="删除区域", notes="根据url的id来指定删除区域信息")
    @ApiImplicitParam(name = "id", value = "区域ID", required = true, dataType = "int" , paramType =  "query")
    @PostMapping("/delete")
    public ResponseResult deleteArea(@RequestParam("id") int id){
        return FormatResponseUtil.formatResponse(areaService.delAreaById(id));
    }





}

访问地址：http://localhost:8086/swagger-ui.html#/

4、注解

@Api：
作用在类上，用来标注该类具体实现内容。表示标识这个类是swagger的资源 。
参数：

1. tags：可以使用tags()允许您为操作设置多个标签的属性，而不是使用该属性。
2. description：可描述描述该类作用。

---

@ApiImplicitParam：
作用在方法上，表示单独的请求参数
参数：

1. name ：参数名。
2. value ： 参数的具体意义，作用。
3. required ： 参数是否必填。
4. dataType ：参数的数据类型。
5. paramType ：查询参数类型，这里有几种形式：

类型	作用
path	以地址的形式提交数据
query	直接跟参数完成自动映射赋值
body	以流的形式提交 仅支持POST
header	参数在request headers 里边提交
form	以form表单的形式提交 仅支持POST

注意：当我发POST请求的时候，当时接受的整个参数，不论我用body还是query，后台都会报Body Missing错误。这个参数和SpringMvc中的@RequestBody冲突，索性我就去掉了paramType，对接口测试并没有影响。

---

@ApiImplicitParams：

用于方法，包含多个 @ApiImplicitParam：

@ApiImplicitParams({
    @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
    @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")
 })

---

@ApiModel：

用于类，表示对类进行说明，用于参数用实体类接收；

@ApiModelProperty：

用于方法，字段 ，表示对model属性的说明或者数据操作更改

@ApiModel(value = "User", description = "用户")
public class User implements Serializable{

   private static final long serialVersionUID = 1546481732633762837L;

   /**
    * 用户ID
    */
   @ApiModelProperty(value = "用户ID", required = true)
   @NotEmpty(message = "{id.empty}", groups = {Default.class,New.class,Update.class})
   protected String id;

   /**
    * code/登录帐号
    */
   @ApiModelProperty(value = "code/登录帐号")
   @NotEmpty(message = "{itcode.empty}", groups = {Default.class,New.class,Update.class})
   protected String itcode;

   /**
    * 用户姓名
    */
   @ApiModelProperty(value = "用户姓名")
   @NotEmpty(message = "{name.empty}", groups = {Default.class,New.class,Update.class})
   protected String name;
}

---

@ApiOperation：

用于方法，表示一个http请求的操作 。

@ApiOperation(value = "获取图书信息", notes = "获取图书信息", response = Book.class, responseContainer = "Item", produces = "application/json")
@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "book's name", required = true, dataType = "Long", paramType = "query"),
        @ApiImplicitParam(name = "date", value = "book's date", required = false, dataType = "string", paramType = "query")})
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
public Book getBook(@PathVariable Long id, String date) {
    return books.get(id);
}

---

@ApiResponse：

用于方法，描述操作的可能响应。

@ApiResponses：

用于方法，一个允许多个ApiResponse对象列表的包装器。
例：

@ApiResponses(value = { 
    @ApiResponse(code = 500, message = "2001:因输入数据问题导致的报错"),
    @ApiResponse(code = 500, message = "403:没有权限"),
    @ApiResponse(code = 500, message = "2500:通用报错（包括数据、逻辑、外键关联等，不区分错误类型）")
})

---

@ApiParam：

用于方法，参数，字段说明，表示对参数的添加元数据（说明或是否必填等）

---

@Authorization：

声明要在资源或操作上使用的授权方案。

---

@AuthorizationScope：

介绍一个OAuth2授权范围。

---

@ResponseHeader：

响应头设置，使用方法。