SpringBoot+Swagger应用

1、POM引入

        <!--swagger2-->
        <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、创建SwaggerConfig

@Configuration
@EnableSwagger2 //启动swagger注解 启动服务，浏览器输入"http://服务名:8080/swagger-ui.html"
public class SwaggerConfig {
    /**
     * 用于配置swagger2，包含文档基本信息
     * 指定swagger2的作用域（这里指定包路径下的所有API）
     * @return Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //指定需要扫描的controller
                .apis(RequestHandlerSelectors.basePackage("com.seata.business.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 构建文档基本信息，用于页面显示，可以包含版本、
     * 联系人信息、服务地址、文档描述信息等
     * @return ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //标题
                .title("系统 API")
                .description("接口测试文档")
                .termsOfServiceUrl("http://localhost:8080")
                //设置联系方式
                .contact(new Contact("测试", "文档地址", "邮箱"))
                .version("1.0")
                .build();
    }
}

3、Controller 应用

@Api(tags = "测试模块")
@RestController
@RequestMapping("/business")
public class BusinessController {
    @Autowired
    private BusinessService businessService;
    @Autowired
    private RedisService redisService;
    @Autowired
    private RestTemplate restTemplate;

    /**
     * 提交事务  提交创建订单日志,扣减库存  ,下订单
     * @return
     */
    @ApiOperation(value = "分布式事务测试", notes = "描述信息")
    @RequestMapping(value = "/purchase/commit", method = RequestMethod.GET)
    public String purchaseCommit(){
        try {
            businessService.purchase(8001l, 7001l, 30);
        } catch (Exception exx) {
            return exx.getMessage();
        }
        return "全局事务提交";
    }
    @ApiOperation(value = "获取日志详细信息", notes = "根据id查询")
    @ApiImplicitParam(name = "id", value = "唯一标识", required = true, dataType = "int",paramType = "path")
    @RequestMapping(value = "/cash/query", method = RequestMethod.GET)
    public Log find(Long id){
        return businessService.findLogById(id);
    }
    @ApiOperation(value = "更新日志信息", notes = "更新日志")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "唯一标识", required = true, dataType = "int",paramType = "path"),
            @ApiImplicitParam(name = "name", value = "名称", required = true, dataType = "String")
    })
    @RequestMapping(value = "/cash/update", method = RequestMethod.GET)
    public Log update(Long id){
        Log log = new Log();
        log.setId(id.intValue());
        return businessService.update(log);
    }
    @ApiOperation(value = "删除日志信息", notes = "根据id删除")
    @ApiImplicitParam(name = "id", value = "唯一标识", required = true, dataType = "int",paramType = "path")
    @RequestMapping(value = "/cash/remove", method = RequestMethod.GET)
    public String remove(Long id){
        businessService.remove(id);
        return "删除成功";
    }
    @ApiOperation(value = "事务测试", notes = "事务测试")
    @RequestMapping(value = "/transaction/demo", method = RequestMethod.GET)
    public String transaction(){
        businessService.transactionDemo();
        return "事务测试";
    }
    /**
     * 负载均衡测试
     * @return
     */
    @ApiOperation(value = "负载均衡测试", notes = "ribbon")
    @RequestMapping(value = "/ribbon", method = RequestMethod.GET)
    public String ribbon(){
        businessService.transactionDemo();
        return businessService.ribbon();
    }
    /**
     * 负载均衡测试
     * @return
     */
    @ApiOperation(value = "负载均衡测试", notes = "restTemplate")
    @RequestMapping(value = "/getRibbon", method = RequestMethod.GET)
    public  String getRibbon(){
        // order 使用rpc远程技术调用服务 ,2种调用方法，一种是名称（要开启负载均衡），一个是域名（不用开启负载均衡）
         String memberUrl = "http://seata-order/order/ribbon";
//        String memberUrl = "http://192.168.1.225:18001/order/ribbon";
        String result = restTemplate.getForObject(memberUrl,String.class);
        System.out.println("调用Order服务，result："+result);
        return  result;
    }
}

效果图

备注：在 @RequestMapping(value = “/getRibbon”, method = RequestMethod.GET)中，如果不写method = RequestMethod.GET，则效果图如下：

4、swagger2注解说明

针对swagger2的注解，在使用中，大致可以分为如下几类：对象、方法、类、参数、响应。

针对类的注解：
@Api：修饰controller，用来描述该controller所代表的含义。其中比较常见的有如下几个参数：
      tags：指定该controller的标签，也就说该controller的含义。例如用户模块、权限模块等。
      producer：指定controller统一采用的响应格式。
      protocols：指定协议。
针对方法的注解：
@ApiOperation：修饰controller下面的方法，用来描述该方法的作用。其中比较常见的有如下几个参数：
     value：描述该方法用途。
     note：对该方法的内容进行详细描述。
     httpMethod：使用什么http方法。
针对参数的注解：
@ApiImplicitParam：用于描述请求参数，一个该注解描述一个参数。其中比较常见的有如下几个参数：
     name：参数名。
     value： 参数的含义。
     required：参数是否必传。
     paramType：参数所存在的位置。有一下几种类型：
            · header：表示从header中获取。@RequestHeader
            · query：表示从地址栏问号后面获取。@RequestParam
            · path：表示从URL中获取。@PathVariable
            · body：表示从body中获取。
            · form：表示从form表单中获取。
     dataType：参数类型，默认String。
     defaultValue：参数的默认值。
@ApiImplicitParams：用于描述多个参数。可以包含多个@ApiImplicitParam。
针对响应的注解：
@ApiResponse：用于描述HTTP其中的一种响应。其中比较常见的有如下几个参数：
     code：int类型，用于表示状态码。例如：405。
     message：用于描述该码值所代表的具体含义。
     response：抛出异常类。
@ApiResponses：用于描述多个HTTP响应码。可以包含多个@ApiResponse。
针对对象的注解：
@ApiModel：被用来描述某个对象。可以是接口请求参数对象，也可以是响应对象。
@ApiModelProperty：用于描述对象字段所代表的含义。
其它注解：
@ApiIgnore：该注解表示，swagger2在生成文档的时候，忽略该方法或类。

1. @Api：用在请求的类上，说明该类的作用

说明：
1 @Api：用在请求的类上，说明该类的作用
2     tags="说明该类的作用"
3     value="该参数没什么意义，所以不需要配置"
示例：
1   @Api(tags="APP用户注册Controller")

2. @ApiOperation：用在请求的方法上，说明方法的作用

说明：
1 @ApiOperation："用在请求的方法上，说明方法的作用"
2     value="说明方法的作用"
3     notes="方法的备注说明"
示例：
1  @ApiOperation(value="用户注册",notes="手机号、密码都是必输项，年龄随边填，但必须是数字")

3. @ApiImplicitParams：用在请求的方法上，包含一组参数说明

说明：
 1 @ApiImplicitParams：用在请求的方法上，包含一组参数说明
 2     @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息       
 3         name：参数名
 4         value：参数的汉字说明、解释
 5         required：参数是否必须传
 6         paramType：参数放在哪个地方
 7             · header --> 请求参数的获取：@RequestHeader
 8             · query --> 请求参数的获取：@RequestParam
 9             · path（用于restful接口）--> 请求参数的获取：@PathVariable
10             · body（不常用）
11             · form（不常用）    
12         dataType：参数类型，默认String，其它值dataType="Integer"       
13         defaultValue：参数的默认值
示例：
@ApiImplicitParams({
    @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})

4. @ApiResponses：用于请求的方法上，表示一组响应

说明：
1 @ApiResponses：用于请求的方法上，表示一组响应
2     @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
3         code：数字，例如400
4         message：信息，例如"请求参数没填好"
5         response：抛出异常的类
示例：
1 @ApiOperation(value = "select1请求",notes = "多个参数，多种的查询参数类型")
2 @ApiResponses({
3     @ApiResponse(code=400,message="请求参数没填好"),
4     @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
5 })

5. @ApiModel：用于响应类上，表示一个返回响应数据的信息

说明：
1 @ApiModel：用于响应类上，表示一个返回响应数据的信息
2             （这种一般用在post创建的时候，使用@RequestBody这样的场景，
3             请求参数无法使用@ApiImplicitParam注解进行描述的时候）
4     @ApiModelProperty：用在属性上，描述响应类的属性
示例：
 1 import io.swagger.annotations.ApiModel;
 2 import io.swagger.annotations.ApiModelProperty;
 3 
 4 import java.io.Serializable;
 5 
 6 @ApiModel(description= "返回响应数据")
 7 public class RestMessage implements Serializable{
 8 
 9     @ApiModelProperty(value = "是否成功")
10     private boolean success=true;
11     @ApiModelProperty(value = "返回对象")
12     private Object data;
13     @ApiModelProperty(value = "错误编号")
14     private Integer errCode;
15     @ApiModelProperty(value = "错误信息")
16     private String message;
17 
18     /* getter/setter */
19 }