Spring Boot项目开发（五）——集成swagger2自动生成接口文档

一、添加swagger2相关依赖

<!--添加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>

二、开启swagger2

启动类添加@EnableSwagger2注解，开启swagger2

package com.learn.mall;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@MapperScan(basePackages = "com.learn.mall.model.dao")
@EnableSwagger2
public class MallApplication {

    public static void main(String[] args) {
        SpringApplication.run(MallApplication.class, args);
    }

}

三、编写相关配置文件

package com.learn.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;

//访问http://localhost:8080/swagger-ui.html可以看到API文档
@Configuration
public class SpringFoxConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("SpringBoot学习项目")
                .description("")
                .termsOfServiceUrl("")
                .build();
    }
}

package com.learn.mall.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;


/**
 * 配置地址映射
 */
@Configuration
public class LearnMallWebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry){
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

四、controller添加相关接口描述

controller层通过@ApiOperation("添加商品分类")注解可添加接口描述

package com.learn.mall.controller;

import com.learn.mall.common.ApiRestResponse;
import com.learn.mall.common.Constant;
import com.learn.mall.exception.LearnMallExceptionEnum;
import com.learn.mall.model.pojo.User;
import com.learn.mall.model.request.AddCategoryRequest;
import com.learn.mall.service.CategoryService;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.ResponseBody;

import javax.servlet.http.HttpSession;

/**
 * 商品分类管理
 */
@Controller
public class CategoryController {

    @Autowired
    CategoryService categoryService;
    /**
     * 添加商品分类
     *
     * @param session
     * @return
     */
    @ApiOperation("添加商品分类")
    @PostMapping("admin/category/add")
    @ResponseBody
    public ApiRestResponse addCategory(HttpSession session, @RequestBody @Validated AddCategoryRequest categoryRequest) {
        //判断用户是否登录
        User user = (User) session.getAttribute(Constant.USER);
        if(user == null){
            return ApiRestResponse.error(LearnMallExceptionEnum.NEED_LOGIN);
        }
        //判断用户是否是超级管理员
        if(user.getRole().equals(1)){
            return ApiRestResponse.error(LearnMallExceptionEnum.NEED_ADMIN);
        }else{
            //执行添加操作
            categoryService.addCategory(categoryRequest);
            return ApiRestResponse.success();
        }
    }
}

五、访问http://localhost:8080/swagger-ui.html即可