Mall项目--swagger2 入门

前面参照开源项目Mall，进行学习，写了一个CRUD! 再次基础上进行一些中间件的使用，熟悉一下！首先就是swagger！ 参照了一些博客发现swagger的使用主要分为四个阶段

• 1、导入Swaggerr依赖
• 2、配置Docket的bean
• 3、使用@Api等注解修饰 ** 正常来说，配置以上三步就可以了，但如果配置了跨域，则需要配置静态资源**

1.导入依赖资源配置！

<!--Swagger-UI API文档生产工具-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

2、使用开启注解 @EnableSwagger2 (@enableswagger放置在swaggerconfig和启动类上都可以)和 配置映射路径、要扫描的接口、文档网站信息

package com.cao.mall.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

public class Swagger2Config {

    /**
     * 配置docker的bean
     */

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                // 接口文档的基本信息
                .apiInfo(apiInfo())
                //为当前包下controller生成API文档
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cao.mall.controller"))
                //为有@Api注解的Controller生成API文档    @Api()用于类名
                //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                //为有@ApiOperation注解的方法生成API文档     @ApiOperation()用于方法名
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                // 路径使用any风格
                .paths(PathSelectors.any())

                // 如何保护我们的Api，有三种验证（ApiKey, BasicAuth, OAuth）
                //.securitySchemes(security())
                .build();
    }


    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("CSC的mall")
                .description("first-mall")
                .contact("CSC")
                .version("1.0")
                .build();
    }


}

3.在 Controller 中增加 Swagger2 相关注解 在此之前要了解一些相关的常用注解 Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：

-   @Api：修饰整个类，描述Controller的作用
-   @ApiOperation：描述一个类的一个方法，或者说一个接口
-   @ApiParam：单个参数描述
-   @ApiModel：用对象来接收参数
-   @ApiProperty：用对象接收参数时，描述对象的一个字段
-   @ApiResponse：HTTP响应其中1个描述
-   @ApiResponses：HTTP响应整体描述
-   @ApiIgnore：使用该注解忽略这个API
-   @ApiError ：发生错误返回的信息
-   @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
-   @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

package com.cao.mall.controller;

import com.cao.mall.common.api.CommonPage;
import com.cao.mall.common.api.CommonResult;
import com.cao.mall.mbg.model.PmsBrand;
import com.cao.mall.service.PmsBrandService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;

import org.slf4j.Logger;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.service.Tags;

import java.util.List;



//@RestController
@Controller
@RequestMapping("/brand")
@Api(tags="PmsBrandController",description = "商品品牌管理")
public class PmsBrandController {

    @Autowired
    private PmsBrandService pmsBrandService;

    private static final Logger LOGGER= LoggerFactory.getLogger(PmsBrandController.class);


    @ApiOperation("获取所有品牌列表")
    @ResponseBody
    @RequestMapping(value = "listAll",method = RequestMethod.GET)
    public CommonResult<List<PmsBrand>> getBrandList(){
        return CommonResult.success(pmsBrandService.listAllBrand());
    }

    @ApiOperation("新建品牌")
    @RequestMapping(value = "/create", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
        CommonResult commonResult;
        int count = pmsBrandService.creatBrand(pmsBrand);
        if (count == 1) {
            commonResult = CommonResult.success(pmsBrand);
            LOGGER.debug("createBrand success:{}", pmsBrand);
        } else {
            commonResult = CommonResult.failed("操作失败");
            LOGGER.debug("createBrand failed:{}", pmsBrand);
        }
        return commonResult;
    }

    @ApiOperation("更新品牌")
    @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrand, BindingResult result) {

        CommonResult commonResult;
        int count = pmsBrandService.updateBrand(id,pmsBrand);
        if (count == 1) {
            commonResult = CommonResult.success(pmsBrand);
            LOGGER.debug("createBrand success:{}", pmsBrand);
        } else {
            commonResult = CommonResult.failed("操作失败");
            LOGGER.debug("createBrand failed:{}", pmsBrand);
        }
        return commonResult;
    }


    @ApiOperation("删除品牌")
    @RequestMapping(value = "/delete/{id}", method = RequestMethod.POST)
    @ResponseBody
    public CommonResult deleteBrand(@PathVariable("id") Long id){
        int count=pmsBrandService.deleteBrand(id);
        if(count==1){
            LOGGER.debug("deleteBrand success :id={}",id);
            return CommonResult.success(null);
        }else{
            LOGGER.debug("deleteBrand failed :id={}",id);
            return CommonResult.failed("操作失败");

        }
    }
   

    @ApiOperation("分页查询品牌列表")
    @RequestMapping(value = "/list", method = RequestMethod.GET)
    @ResponseBody
    public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1") Integer pageNum,
                                                        @RequestParam(value = "pageSize", defaultValue = "3") Integer pageSize) {
        List<PmsBrand> brandList = pmsBrandService.listBrand(pageNum, pageSize);
        return CommonResult.success(CommonPage.restPage(brandList));
    }

    @ApiOperation("获取指定id品牌详情")
    @RequestMapping(value = "/id", method = RequestMethod.GET)
    @ResponseBody
    public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {

        return CommonResult.success(pmsBrandService.getBrand(id));
    }



}

就是一些CRUD，一些代码没贴上去~

4.如果 配置跨域， Spring Boot 项目中如果集成了 Spring Security，在不做额外配置的情况下，Swagger2 文档会被拦截则需要配置第四步！

package io.xiongdi.config;

import io.xiongdi.interceptor.AuthorizationInterceptor;
import io.xiongdi.resolver.LoginUserHandlerMethodArgumentResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.method.support.HandlerMethodArgumentResolver;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.util.List;

/**
 * @author wujiaxing
 * <p>
 *     此配置类可配置拦截器、参数解析器、返回值解析器、跨域支持等等
 * </p>
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Autowired
    private AuthorizationInterceptor authorizationInterceptor;
    @Autowired
    private LoginUserHandlerMethodArgumentResolver loginUserHandlerMethodArgumentResolver;

    /**
     *  如果配置跨域，就增加这个配置
     * @param registry
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("/static/");
        registry.addResourceHandler("/js/**").addResourceLocations("/js/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars");
    }

    /**
     * 拦截器配置
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authorizationInterceptor).addPathPatterns("/api/**");
    }

    /**
     * 跨域支持配置
     * @param registry
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**").allowCredentials(true).allowedOrigins("*").allowedMethods("GET", "PUT", "DELETE", "POST", "OPTIONS").maxAge(3600);
    }

    /**
     * 参数解析配置
     * @param resolvers
     */
    @Override
    public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(loginUserHandlerMethodArgumentResolver);
    }
}