SpringBoot整合swagger实现接口管理

版权声明：本文为博主原创文章，未经博主允许不得转载。 https://blog.csdn.net/qq_38616723/article/details/82222952

• pom.xml
  pom.xml文件加入swagger坐标

<swagger.version>2.6.1</swagger.version>
 <dependency>
      <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
      </dependency>

      <dependency>
           <groupId>io.springfox</groupId>
           <artifactId>springfox-swagger-ui</artifactId>
           <version>${swagger.version}</version>
  </dependency>

我附上我整个pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.bl</groupId>
    <artifactId>bl-master</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>pom</packaging>

    <name>bl-master</name>
    <description>Demo project for Spring Boot</description>

    <modules>
        <module>blstation-common</module>
        <module>blstation-dao</module>
        <module>blstation-entity</module>
        <module>blstation-interface</module>
        <module>blstation-service</module>
        <module>blstation-web</module>
    </modules>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
        <mybatis-spring-boot-starter.version>1.3.2</mybatis-spring-boot-starter.version>
        <mysql.version>5.1.45</mysql.version>
        <druid.version>1.1.10</druid.version>
        <logback.version>1.1.7</logback.version>
        <slf4j.version>1.6.4</slf4j.version>
        <kaptcha.version>2.3.2</kaptcha.version>
        <commons-beanutils>1.9.3</commons-beanutils>
        <commons-collections>3.2.2</commons-collections>
        <commons-codec>1.10</commons-codec>
        <commons-io>2.6</commons-io>
        <commons-lang3>3.5</commons-lang3>
        <lombok.version>1.16.10</lombok.version>
        <pagehelper-spring-boot-starter.version>1.2.5</pagehelper-spring-boot-starter.version>
        <fastdfs-client.version>1.26.2</fastdfs-client.version>
        <guava.version>2.9.0</guava.version>
        <swagger.version>2.6.1</swagger.version>
    </properties>


    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.0.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
        </dependency>


        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>

            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>

            <dependency>
                <groupId>com.fasterxml.jackson.datatype</groupId>
                <artifactId>jackson-datatype-guava</artifactId>
                <version>${guava.version}</version>
            </dependency>
            <!-- FASTdfs -->
            <dependency>
                <groupId>com.github.tobato</groupId>
                <artifactId>fastdfs-client</artifactId>
                <version>${fastdfs-client.version}</version>
            </dependency>
            <!-- 分页插件 -->
            <dependency>
                <groupId>com.github.pagehelper</groupId>
                <artifactId>pagehelper-spring-boot-starter</artifactId>
                <version>${pagehelper-spring-boot-starter.version}</version>
            </dependency>
            <!-- 连接池 -->
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>druid</artifactId>
                <version>${druid.version}</version>
            </dependency>

            <dependency>
                <groupId>org.mybatis.spring.boot</groupId>
                <artifactId>mybatis-spring-boot-starter</artifactId>
                <version>${mybatis-spring-boot-starter.version}</version>
            </dependency>
            <!-- logback start -->
            <dependency>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-api</artifactId>
                <version>${slf4j.version}</version>
                <scope>compile</scope>
            </dependency>
            <dependency>
                <groupId>ch.qos.logback</groupId>
                <artifactId>logback-core</artifactId>
                <version>${logback.version}</version>
            </dependency>
            <dependency>
                <groupId>ch.qos.logback</groupId>
                <artifactId>logback-classic</artifactId>
                <version>${logback.version}</version>
            </dependency>

            <!-- 日志处理 -->
            <dependency>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-log4j12</artifactId>
                <version>${slf4j.version}</version>
            </dependency>

            <dependency>
                <groupId>mysql</groupId>
                <artifactId>mysql-connector-java</artifactId>
                <version>${mysql.version}</version>
            </dependency>


            <!-- tools start -->
            <dependency>
                <groupId>commons-beanutils</groupId>
                <artifactId>commons-beanutils</artifactId>
                <version>${commons-beanutils}</version>
            </dependency>
            <dependency>
                <groupId>commons-collections</groupId>
                <artifactId>commons-collections</artifactId>
                <version>${commons-collections}</version>
            </dependency>

            <dependency>
                <groupId>commons-codec</groupId>
                <artifactId>commons-codec</artifactId>
                <version>${commons-codec}</version>
            </dependency>
            <dependency>
                <groupId>commons-io</groupId>
                <artifactId>commons-io</artifactId>
                <version>${commons-io}</version>
            </dependency>

            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-lang3</artifactId>
                <version>${commons-lang3}</version>
            </dependency>
            <!-- tools end -->

            <!-- https://mvnrepository.com/artifact/com.github.penggle/kaptcha -->
            <dependency>
                <groupId>com.github.penggle</groupId>
                <artifactId>kaptcha</artifactId>
                <version>${kaptcha.version}</version>
            </dependency>

            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </dependency>
        </dependencies>

    </dependencyManagement>

    <build>
        <finalName>${project.artifactId}</finalName>
        <plugins>
            <!-- 资源文件拷贝插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-resources-plugin</artifactId>
                <version>2.7</version>
                <configuration>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
            <!-- java编译插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.7.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
        </plugins>
        <pluginManagement>
            <plugins>
                <!-- 配置Tomcat插件 -->
                <plugin>
                    <groupId>org.apache.tomcat.maven</groupId>
                    <artifactId>tomcat7-maven-plugin</artifactId>
                    <version>2.2</version>
                </plugin>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <configuration>
                        <skip>true</skip>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.3</version>
                    <configuration>
                        <source>1.8</source>
                        <target>1.8</target>
                        <encoding>UTF-8</encoding>
                    </configuration>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

• 接下来写一个Swagger2的类去实现WebMvcConfigurer

package com.bl.station.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

/**
 * @ClassName Swagger2
 * @Description TODO
 * @Date 2018/8/14 17:55
 * @Author itastro
 * @Version 1.0
 **/
//注解标示,这是一个配置类,@Configuation注解包含了@Component注解
//可以不用在使用@Component注解标记这是个bean了

@Configuration
@EnableWebMvc

public class Swagger2 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/");
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bl.station.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("API")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

然后在SpringBoot启动类上加上@EnableSwagger2注解

@EnableSwagger2

然后去访问 http://ip/blstation-web/swagger-ui.html 这个路径

关于Swagger一些注解的解释

@ApiModelProperty()用于字段,表示对model属性的说明,使用方式如下：

package com.bl.station.param;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.*;
import org.hibernate.validator.constraints.Length;
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.web.multipart.MultipartFile;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import java.util.Date;

/**
 * @ClassName HonorParam
 * @Description TODO
 * @Date 2018/8/13 15:01
 * @Author itastro
 * @Version 1.0
 **/
@ApiModel
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class HonorParam {
    @ApiModelProperty(name = "pic", value = "荣誉资质照片")
    @NotNull(message = "照片不能为空")
    private MultipartFile pic;

    private Integer id;
    @ApiModelProperty(name = "title", value = "荣誉资质标题")
    @Length(max = 50, message = "标题不能大于50个字")
    @NotBlank(message = "标题不能为空")
    private String title;
    @Length(max = 250, message = "备注不能超过250个字")
    @ApiModelProperty(name = "remark", value = "荣誉资质备注")
    private String remark;
    @ApiModelProperty(name = "expired", value = "荣誉资质过期日期")
    @NotNull(message = "过期日不能为空")
    @DateTimeFormat(pattern="yyyy-MM-dd hh:mm:ss")
    private Date expired;
    @ApiModelProperty(name = "content", value = "荣誉资质内容")
    @NotBlank(message = "内容不能为空")
    private String content;
}

@ ApiParam用于Controller中方法的参数说明，使用方式如下：

@PostMapping("/login")
public ResponseData login(
 @ApiParam(value = "登录参数", required = true) 
 @RequestBody LoginQuery query) {
}

value：参数说明

required：是否必填

@ApiOperation用在Controller里的方法上，说明方法的作用，每一个接口的定义,使用方式如下：

@ApiOperation(value = "用户登录", notes = "企业用户认证接口，参数为必填项")
@PostMapping("/login")
public ResponseData login(
 @ApiParam(value = "登录参数", required = true) 
 @RequestBody LoginQuery query) {
}

value：接口名称

notes：详细说明

ApiResponse和ApiResponses

@ApiResponse用于方法上，说明接口响应的一些信息，@ApiResponses组装多个@ApiResponse，使用方式如下：

@ApiResponses({ @ApiResponse(code = 403, message = "无权限访问") })
public ResponseData login(
 @ApiParam(value = "登录参数", required = true) 
 @RequestBody LoginQuery query) {
}

code：响应状态码

message：状态码对应的说明

ApiImplicitParam和ApiImplicitParams

用于方法上，为单独的请求参数进行说明，使用方式如下：

@ApiImplicitParams({ 
 @ApiImplicitParam(name="uid", value="用户ID", required=true,
 paramType="query", dataType="String", defaultValue="1")
}) @GetMapping("/hello") public String hello(String uid) { return uid;
}

name：参数名，对应方法中单独的参数名称

value：参数中文说明

required：是否必填

paramType：参数类型，取值为path, query, body, header, form

dataType：参数数据类型

defaultValue：默认值

@API 作用于controller

@Api(description = "公司荣誉资质api")
@RestController
@RequestMapping("/honor")
public class HonorController {


}

更多内容请看swagger 官网