spring boot集成swagger2

SpringBoot集成Swagger2教程

最新推荐文章于 2025-08-22 14:09:42 发布

转载最新推荐文章于 2025-08-22 14:09:42 发布 · 41 阅读

0 ·

CC 4.0 BY-SA版权

原文链接：http://www.cnblogs.com/zuosl/p/9596837.html

本文详细介绍如何在SpringBoot项目中集成Swagger2实现API文档自动生成。包括添加依赖、配置类编写、Controller注解使用等步骤，并提供中文显示及常见问题解决方案。

spring boot版本2.0.4

swagger版本2.7.0

第一步、在pom文件中添加swagger的相关依赖

<swagger.version>2.7.0</swagger.version>

<!-- Swagger2依赖  -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- Swagger2 UI依赖  -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

第二步、在Application同级目录下创建Swagge配置类

Swagger

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2 API配置
 * @author sushengbuyu
 * @date 2018/9/6 9:04
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.sushengbuyu.life.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * Api的基本信息
     * @return ApiInfo
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("使用Swagger2构建RESTful APIs")
                .contact(new Contact("苏生不语", "https://www.cnblogs.com/zuosl/", "18761647971@163.com"))
                .version("1.0")
                .build();
    }
}

第三步、在Controller使用@Api注解

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.sushengbuyu.life.common.ErrorCode;
import com.sushengbuyu.life.common.Result;
import com.sushengbuyu.life.entity.User;
import com.sushengbuyu.life.service.UserService;
import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;

/**
 * <p>
 * 用户表 前端控制器
 * </p>
 *
 * @author sushengbuyu
 * @since 2018-09-04
 */
@Api(tags = {"用户接口"})
@RestController
@RequestMapping("/users")
public class UserController extends BaseController{

    @Autowired
    private UserService userService;

    @ApiOperation(value = "用户列表", notes = "获取所有用户列表")
    @GetMapping
    public Result list(){
        Page<User> page = (Page<User>) userService.page(new Page<User>(1,10), new QueryWrapper<User>().orderByDesc("create_time"));
        return success(page);
    }

    @ApiOperation(value = "新增用户", notes = "添加一个用户")
    @PostMapping
    public Result add(@ModelAttribute User user){
        boolean result = userService.save(user);
        return result ? success(null) : failed(ErrorCode.FAILED);
    }

    @ApiOperation(value = "用户详细", notes = "根据ID获取用户信息")
    @GetMapping("{id}")
    public Result getUser(@PathVariable long id){
        User user = userService.getById(id);
        return user != null?success(user) : failed(ErrorCode.USER_NOTFOUND);
    }

    @ApiOperation(value = "修改用户", notes = "根据ID修改用户信息")
    @PutMapping("{id}")
    public Result updateUser(@PathVariable long id,User user){
        user.setUid(id);
        boolean result = userService.updateById(user);
        return result ? success(null) : failed(ErrorCode.USER_NOTFOUND);
    }

    @ApiOperation(value = "删除用户", notes = "根据ID删除用户")
    @DeleteMapping("{id}")
    public Result deleteUser(@PathVariable long id){
        boolean result = userService.removeById(id);
        return result ? success(null) : failed(ErrorCode.USER_NOTFOUND);
    }

}

第四步、启动项目

访问http://localhost:{你的端口}/swagger-ui.html

第五步、显示中文

双击shift建，输入swagger-ui.html，在resources目录下新建META-INF\resources目录，把找到的swagger-ui.html复制过来

打开文件，在head标签里面添加下面的代码

<!--国际化操作：选择中文版 -->
    <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

重启项目，再打开swagger就是中文显示了

备注：

原本Controller使用@Api(value="XX接口")的

后来发现value设置了没有效果，改成了@Api(tags={"XX接口"})页面才显示中文。。。

如果你项目中使用了@EnableWebMvc需要手动设置swagger-ui.html的位置

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/statics/**").addResourceLocations("classpath:/statics/");
        // 解决 SWAGGER 404报错
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

转载于:https://www.cnblogs.com/zuosl/p/9596837.html