SpringBoot程序配置及使用swagger

提问：swagger和Yapi有什么区别，通过Swagger就可以生成接口文档,那么我们是不是就不需要Yapi了?

答：

1、Yapi是设计阶段使用的工具,管理和维护接口

2、Swagger在开发阶段使用的框架,帮助后端开发人员做后端的接口测试

————————————————————

一、导入knife4j的maven坐标

<dependency>
    <groupld>com.github.xiaoymin</groupld>
    <artifactld>knife4j-spring-boot-starter</artifactld>
    <version>3.0.2</version>
</dependency>

二、在配置类中加入knife4j相关配置

    /**
     * 通过knife4j生成接口文档
     * @return
     * SpringBoot程序启动之后就会执行此方法，并且把这个对象创建出来
     */
    @Bean
    public Docket docketToAdmin() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("苍穹外卖项目接口文档")
                .version("2.0")
                .description("苍穹外卖项目接口文档")
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理端接口")
                .apiInfo(apiInfo)
                .select()
                //扫描com.sky.controller.admin包及其子包，扫描到之后就可以通过反射解析类及其方法来帮助我们生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                .paths(PathSelectors.any())
                .build();
        log.info("创建管理端接口");
        return docket;
    }

三、设置静态资源映射,否则接口文档页面无法访问

    /**
     * 设置静态资源映射
     * 不设置这个映射的话，MVC会以为我们在访问某个controller，而不是静态资源
     * 会误认为这个请求是一个动态请求，而不是静态请求
     * @param registry
     * 该方法是重写的父类的方法
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

四、访问接口文档主页

访问路径：localhost:8080/doc.html

五、使用

注解说明
@Api 用在类上,例如Controller,表示对类的说明

@ApiOperation 用在方法上,例如Controller的方法,说明方法的用途、作用

//指定bean的名称，防止容器里bean冲突
@RestController("adminShopController")
@RequestMapping("/admin/shop")
@Api("店铺相关接口")
@Slf4j
public class ShopController {

    public static final String KEY="SHOP_STATUS";

    @Autowired
    private RedisTemplate redisTemplate;

    /**
     * 设置店铺状态
     * @param status
     * @return
     */
    @PutMapping("/{status}")
    @ApiOperation("设置店铺状态")
    public Result setStatus(@PathVariable Integer status){
        redisTemplate.opsForValue().set(KEY,status);
        log.info("设置店铺营业状态");
        return Result.success();
    }

    /**
     * 获取店铺营业状态
     * @return
     */
    @GetMapping("/status")
    @ApiOperation("admin获取店铺营业状态")
    public Result getStatue(){
        Integer status = (Integer) redisTemplate.opsForValue().get(KEY);
        log.info("查询店铺营业状态");
        return Result.success(status);
    }
}

在接口文档里可以对接口进行测试

注意：程序使用了 jwt令牌的话，测试的时候需要在请求头携带上令牌参数，我们只需先进行登录获取到令牌，添加全局参数即可，注意每次登陆令牌都会变，所以记得更换

五、常用注解