SpringBoot整合Swagger及简单使用

1. pom.xml文件引入相关的jar包

<!-- swagger接口管理 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>

2. 创建Swagger配置类，配置Swagger

package com.example.demo.config;

import springfox.documentation.service.Contact;
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;

/**
 * Created by Zpy on 2020/04/28.
 */
@Configuration
@EnableSwagger2
public class SwaggerApp {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 存放接口的Controller的包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Name", "URL", "Email"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

3.在需要配置的地方使用@Api***相关注解进行相关的配置

Controller层注解示例：

package com.example.demo.controller;

import com.example.demo.entry.Person;
import com.example.demo.service.IPersonService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

import java.util.ArrayList;
import java.util.List;

@Controller
@Api(description = "主测试入口类", tags = "TestController")
public class TestController {

    @RequestMapping("/getPerson")
    @ResponseBody
    @ApiOperation(value = "获取用户信息", notes = "获取用户信息接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "str1", value = "参数一", paramType = "query", required = true, dataType = "String"),
            @ApiImplicitParam(name = "str2", value = "参数二", paramType = "query", required = true, dataType = "String")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功！", response = Person.class),
            @ApiResponse(code = 404, message = "请求路径未找到！", response = Person.class)
    })
    public List<Person> getMap(@ApiParam(name = "str1", value = "参数一", required = true) String str1, String str2) {
        System.out.println("参数一输出：" + str1 + ", \n参数二输出：" + str2);

        ArrayList<Person> list = new ArrayList<>();
        list.add(new Person("张三", 15, "13728726789", Byte.valueOf("1")));

        return list;
    }
}

Dao层注解示例：

package com.example.demo.entry;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.ToString;
import org.springframework.stereotype.Repository;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ToString
@Repository
@ApiModel(value = "Person对象", description = "用户对象")
public class Person {
    @ApiModelProperty(value = "名称", dataType = "String", name = "name", example = "阿凡达", required = false, hidden = false)
    private String name;
    @ApiModelProperty(value = "年龄", dataType = "Integer", name = "age", example = "18", required = false, hidden = false)
    private Integer age;
    @ApiModelProperty(value = "手机号", dataType = "String", name = "tel", example = "13929282928", required = false, hidden = false)
    private String tel;
    @ApiModelProperty(value = "性别", dataType = "byte", name = "sex", example = "1", required = false, hidden = false)
    private byte sex;
}

本项目端口号8091，访问路径：http://localhost:8091/swagger-ui.html展示：

4. 配置多个Controller

方法一：指定配置文件api包为controller公共的父包

package com.example.config;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import io.swagger.annotations.Api;
import springfox.documentation.RequestHandler;
import springfox.documentation.service.Contact;
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;

/**
 * Created by zpy on 2020/04/21.
 */
@Configuration
@EnableSwagger2
public class SwaggerApp {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
				.apis(RequestHandlerSelectors.basePackage("com.example"))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Name", "URL", "Email"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

方法二：根据共有注解去扫描Controller

package com.example.config;

import com.google.common.base.Predicate;
import com.google.common.base.Predicates;
import io.swagger.annotations.Api;
import springfox.documentation.RequestHandler;
import springfox.documentation.service.Contact;
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;

/**
 * Created by zpy on 2020/04/21.
 */
@Configuration
@EnableSwagger2
public class SwaggerApp {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }
    
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("Name", "URL", "Email"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}