Swagger知识点总结-DX的笔记

1.Swagger是什么？

Swagger[ˈswæɡə®，丝袜哥] ：是一个实现了OpenAPI规范的工具集，用于生成API文档并提供可视化 RESTful 风格的 Web 服务。

OpenAPI规范（OpenAPI Specification 简称OAS）是Linux基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范RESTful服务开发过程。目前V3.0版本的OpenAPI规范已经发布并开源在github上 。

2.为什么要使用Swagger？

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、前后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要。

没有API文档工具之前，大家都是手写API文档的，在什么地方书写的都有，而且API文档没有统一规范和格式，每个公司都不一样。

3.Swagger使用

修改power_shop_item

3.1.pom.xml

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

3.2.config

package com.bjpowernode.config;

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//开启Swagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        //Docket：生成接口文档
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	//基于com.usian.controller生成api文档
                .apis(RequestHandlerSelectors.basePackage("com.usian.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("动力优品后台管理系统")//标题
                .description("商品管理模块接口文档")//描述
                .version("1.0")//版本
                .build();
    }
}

3.3.pojo

package com.bjpowernode.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import java.util.Date;
@ApiModel
public class TbItem {
    @ApiModelProperty(hidden = true)
    private Long id;

    @ApiModelProperty(value="商品名称",required = true)
    private String title;

    @ApiModelProperty(value="卖点",required = true)
    private String sellPoint;

    @ApiModelProperty(value="价格",required = true)
    private Long price;

    @ApiModelProperty(value="库存",required = true)
    private Integer num;
    ... ... ...
}    

3.4.controller

package com.bjpowernode.controller;

import com.bjpowernode.feign.ItemServiceFeign;
import com.bjpowernode.pojo.TbItem;
import com.bjpowernode.utils.PageResult;
import com.bjpowernode.utils.Result;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/backend/item")
@Api("商品管理接口")
public class ItemController {
    @Autowired
    private ItemServiceFeign itemServiceFeignClient;

    /**
     * 查询商品基本信息
     */
    @RequestMapping(value="/selectItemInfo",method = RequestMethod.POST)
    @ApiOperation(value = "查询商品基本信息",notes = "根据itemId查询该商品的基本信息")
    @ApiImplicitParam(name="itemId",type = "Long",value = "商品id")
    public Result selectItemInfo(Long itemId) {
        TbItem tbItem = itemServiceFeignClient.selectItemInfo(itemId);
        if (tbItem != null) {
            return Result.ok(tbItem);
        }
        return Result.error("查无结果");
    }

    /**
     * 查询商品并分页处理
     *
     * @return
     */
    @GetMapping("/selectTbItemAllByPage")
    @ApiOperation(value = "查询商品并分页处理",notes = "分页查询商品信息，每页显示2条")
    @ApiImplicitParams({
        @ApiImplicitParam(name="page",
                              type = "Integer",value = "页码",defaultValue = "1"),
        @ApiImplicitParam(name="rows",
                              type = "Integer",value = "每页多少条",defaultValue = "2")
    })
    public Result selectTbItemAllByPage(@RequestParam(defaultValue = "1")
                  Integer page, @RequestParam(defaultValue = "2") Integer rows) {

        PageResult pageResult = itemServiceFeignClient.selectTbItemAllByPage(page, rows);
        if (pageResult != null && pageResult.getResult() != null &&
                pageResult.getResult().size() > 0) {
            return Result.ok(pageResult);
        }
        return Result.error("查无结果");
    }

    /**
     * 添加商品
     */
    @PostMapping("/insertTbItem")
    @ApiOperation(value = "添加商品",notes = "添加商品及描述和规格参数信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name="desc",type = "String",value = "商品描述信息"),
            @ApiImplicitParam(name="itemParams",type = "String",value = "商品规格参数")
    })
    public Result insertTbItem(TbItem tbItem,String desc,String itemParams){
 		Integer insertTbItemNum = itemServiceFeignClient.insertTbItem(
     											tbItem, desc, itemParams);
        if(insertTbItemNum==3){
            return Result.ok();
        }
        return Result.error("添加失败");
    }
}

3.5.常用注解说明

 @Api：修饰整个类，描述Controller的作用
 @ApiOperation：描述一个类的一个方法，或者说一个接口
 @ApiImplicitParam：单个参数描述
 @ApiImplicitParams：多个参数描述
 @ApiModel：用对象来接收参数
 @ApiModelProperty：用对象接收参数时，描述对象的一个字段
 @ApiResponse：HTTP响应其中1个描述
 @ApiResponses：HTTP响应整体描述

4.访问swagger接口

1、启动服务，然后访问：http://localhost:8091/swagger-ui.html

2、点击item-controller，查看接口信息：

3、点击任意一个接口，即可看到详细信息：

5.测试swagger接口

1、点击Try It Out测试接口：

2、点击execute发送请求：

3、响应结果：

可看到详细信息：