- 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 官网