SpringBoot整合swagger实现接口管理
- pom.xml
pom.xml文件加入swagger坐标
<swagger.version>2.6.1swagger.version>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>${swagger.version}version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>${swagger.version}version>
dependency>我附上我整个pom.xml
<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.0modelVersion>
<groupId>com.blgroupId>
<artifactId>bl-masterartifactId>
<version>0.0.1-SNAPSHOTversion>
<packaging>pompackaging>
<name>bl-mastername>
<description>Demo project for Spring Bootdescription>
<modules>
<module>blstation-commonmodule>
<module>blstation-daomodule>
<module>blstation-entitymodule>
<module>blstation-interfacemodule>
<module>blstation-servicemodule>
<module>blstation-webmodule>
modules>
<properties>
<project.build.sourceEncoding>UTF-8project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8project.reporting.outputEncoding>
<java.version>1.8java.version>
<mybatis-spring-boot-starter.version>1.3.2mybatis-spring-boot-starter.version>
<mysql.version>5.1.45mysql.version>
<druid.version>1.1.10druid.version>
<logback.version>1.1.7logback.version>
<slf4j.version>1.6.4slf4j.version>
<kaptcha.version>2.3.2kaptcha.version>
<commons-beanutils>1.9.3commons-beanutils>
<commons-collections>3.2.2commons-collections>
<commons-codec>1.10commons-codec>
<commons-io>2.6commons-io>
<commons-lang3>3.5commons-lang3>
<lombok.version>1.16.10lombok.version>
<pagehelper-spring-boot-starter.version>1.2.5pagehelper-spring-boot-starter.version>
<fastdfs-client.version>1.26.2fastdfs-client.version>
<guava.version>2.9.0guava.version>
<swagger.version>2.6.1swagger.version>
properties>
<parent>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-parentartifactId>
<version>2.0.0.RELEASEversion>
<relativePath/>
parent>
<dependencies>
<dependency>
<groupId>org.mybatis.spring.bootgroupId>
<artifactId>mybatis-spring-boot-starterartifactId>
dependency>
<dependency>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-testartifactId>
<scope>testscope>
dependency>
<dependency>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-starter-webartifactId>
dependency>
dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger2artifactId>
<version>${swagger.version}version>
dependency>
<dependency>
<groupId>io.springfoxgroupId>
<artifactId>springfox-swagger-uiartifactId>
<version>${swagger.version}version>
dependency>
<dependency>
<groupId>com.fasterxml.jackson.datatypegroupId>
<artifactId>jackson-datatype-guavaartifactId>
<version>${guava.version}version>
dependency>
<dependency>
<groupId>com.github.tobatogroupId>
<artifactId>fastdfs-clientartifactId>
<version>${fastdfs-client.version}version>
dependency>
<dependency>
<groupId>com.github.pagehelpergroupId>
<artifactId>pagehelper-spring-boot-starterartifactId>
<version>${pagehelper-spring-boot-starter.version}version>
dependency>
<dependency>
<groupId>com.alibabagroupId>
<artifactId>druidartifactId>
<version>${druid.version}version>
dependency>
<dependency>
<groupId>org.mybatis.spring.bootgroupId>
<artifactId>mybatis-spring-boot-starterartifactId>
<version>${mybatis-spring-boot-starter.version}version>
dependency>
<dependency>
<groupId>org.slf4jgroupId>
<artifactId>slf4j-apiartifactId>
<version>${slf4j.version}version>
<scope>compilescope>
dependency>
<dependency>
<groupId>ch.qos.logbackgroupId>
<artifactId>logback-coreartifactId>
<version>${logback.version}version>
dependency>
<dependency>
<groupId>ch.qos.logbackgroupId>
<artifactId>logback-classicartifactId>
<version>${logback.version}version>
dependency>
<dependency>
<groupId>org.slf4jgroupId>
<artifactId>slf4j-log4j12artifactId>
<version>${slf4j.version}version>
dependency>
<dependency>
<groupId>mysqlgroupId>
<artifactId>mysql-connector-javaartifactId>
<version>${mysql.version}version>
dependency>
<dependency>
<groupId>commons-beanutilsgroupId>
<artifactId>commons-beanutilsartifactId>
<version>${commons-beanutils}version>
dependency>
<dependency>
<groupId>commons-collectionsgroupId>
<artifactId>commons-collectionsartifactId>
<version>${commons-collections}version>
dependency>
<dependency>
<groupId>commons-codecgroupId>
<artifactId>commons-codecartifactId>
<version>${commons-codec}version>
dependency>
<dependency>
<groupId>commons-iogroupId>
<artifactId>commons-ioartifactId>
<version>${commons-io}version>
dependency>
<dependency>
<groupId>org.apache.commonsgroupId>
<artifactId>commons-lang3artifactId>
<version>${commons-lang3}version>
dependency>
<dependency>
<groupId>com.github.pengglegroupId>
<artifactId>kaptchaartifactId>
<version>${kaptcha.version}version>
dependency>
<dependency>
<groupId>org.projectlombokgroupId>
<artifactId>lombokartifactId>
<version>${lombok.version}version>
dependency>
dependencies>
dependencyManagement>
<build>
<finalName>${project.artifactId}finalName>
<plugins>
<plugin>
<groupId>org.apache.maven.pluginsgroupId>
<artifactId>maven-resources-pluginartifactId>
<version>2.7version>
<configuration>
<encoding>UTF-8encoding>
configuration>
plugin>
<plugin>
<groupId>org.apache.maven.pluginsgroupId>
<artifactId>maven-compiler-pluginartifactId>
<version>3.7.0version>
<configuration>
<source>1.8source>
<target>1.8target>
<encoding>UTF-8encoding>
configuration>
plugin>
plugins>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.tomcat.mavengroupId>
<artifactId>tomcat7-maven-pluginartifactId>
<version>2.2version>
plugin>
<plugin>
<groupId>org.springframework.bootgroupId>
<artifactId>spring-boot-maven-pluginartifactId>
plugin>
<plugin>
<groupId>org.apache.maven.pluginsgroupId>
<artifactId>maven-surefire-pluginartifactId>
<configuration>
<skip>trueskip>
configuration>
plugin>
<plugin>
<groupId>org.apache.maven.pluginsgroupId>
<artifactId>maven-compiler-pluginartifactId>
<version>3.3version>
<configuration>
<source>1.8source>
<target>1.8target>
<encoding>UTF-8encoding>
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 官网