springboot整合Swagger

本文主要讲解springboot是如何通过整合Swagger-UI来实现一份相当完善的在线API文档的。

1. Swagger简介

Swagger-UI是HTML, Javascript, CSS的一个集合，可以动态地根据注解生成在线API文档。

常用注解

• @Api：用于修饰Controller类，生成Controller相关文档信息
• @ApiOperation：用于修饰Controller类中的方法，生成接口方法相关文档信息
• @ApiParam：用于修饰接口中的参数，生成接口参数相关文档信息
• @ApiModelProperty：用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息

2.整合Swagger-UI

2.1 添加项目依赖

在pom.xml文件中加入Swagger-UI相关依赖

<!--  Swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

2.2 添加Swagger-UI的配置

添加Swagger配置类Swagger2Config

package com.mzm.springboot.config;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
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;

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.title}")
    private String title;

    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.mzm.springboot.controller")) //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //为有@Api注解的Controller生成API文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //为有@ApiOperation注解的方法生成API文档
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().
                title("测试Swagger2")
                .description("Spring Boot中使用Swagger2构建RESTful APIs")
                .version("1.0.0")
                .contact(new Contact("mzm", "https://gitee.com/moses_mao", "297531644@qq.com"))
                .build();
    }
}

　Swagger对生成API文档的范围有三种不同的选择

• 生成指定包下面的类的API文档
• 生成有指定注解的类的API文档
• 生成有指定注解的方法的API文档

2.3 controller加入注解

package com.mzm.springboot.controller;

import com.mzm.springboot.controller.common.BaseController;
import com.mzm.springboot.exception.BusinessException;
import com.mzm.springboot.exception.EmBusinessError;
import com.mzm.springboot.response.CommonReturnType;
import com.mzm.springboot.service.UserSevice;
import com.mzm.springboot.service.model.UserModel;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;


@Api(tags = "HomeController", description = "后台首页管理")
@RestController("user")
@RequestMapping("/user")
public class HomeController extends BaseController {

    @Autowired
    private UserSevice userSevice;

    @ApiOperation("hello word")
    @RequestMapping(value = "/hello", method = RequestMethod.GET)
    public String hello() {
        return "hello world";
    }

    @ApiOperation("获取单个用户")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public CommonReturnType getUser(@RequestParam(name = "id") Integer id) throws BusinessException {
        UserModel userModel = userSevice.getUserById(id);
        if (userModel == null) {
            throw new BusinessException(EmBusinessError.USER_NOT_EXISTS);
        }

        return CommonReturnType.create(userModel);
    }
}

3.查看结果

访问Swagger-UI接口文档地址

接口地址：http://localhost:8080/swagger-ui.html