swagger2 配置 生成接口文档
共4步：1.配置依赖jar包==》2.启动类添加启动注解@EnableSwagger2==>3.Swagger2Config配置文件 和 访问入口配置文件==》4.配置controller类
访问：http://localhost:端口号/swagger-ui.html
SRE实战 互联网时代守护先锋，助力企业售后服务体系运筹帷幄！一键直达领取阿里云限量特价优惠。1.依赖
<!--8.接口文档生成-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.启动类注解
@EnableSwagger2
@EnableTransactionManagement // 启注解事务管理，等同于xml配置方式的 <tx:annotation-driven />
@SpringBootApplication
@MapperScan("com.test.springboot.example.mapper")
@EnableCaching //开启缓存
public class SpringbootApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootApplication.class, args);
while (true) {
Scanner scan = new Scanner(System.in);
String question = scan.nextLine();
String answer = question.replace('你', '我').replace('吗', ' ').replace('？', '!');
out.println(answer);
}
}
}
3.2个配置文件
基本配置
package com.test.springboot.config;
import com.test.springboot.bean.ResultModel;
import io.swagger.annotations.*;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.annotations.ApiIgnore;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ResponseMessage;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
/**
* @author zh
* @ClassName cn.saytime.Swgger2
* @Description
* @date 2017-07-10 22:12:31
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
//访问：http://localhost:端口号/swagger-ui.html
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("中国组")//
.directModelSubstitute(LocalDate.class, String.class)//
.genericModelSubstitutes(ResponseEntity.class)//
.useDefaultResponseMessages(false)//
.globalResponseMessage(RequestMethod.POST, ResultModel.customerResponseMessage())//设置POST方法返回值
.globalResponseMessage(RequestMethod.GET, ResultModel.customerResponseMessage())//
.globalResponseMessage(RequestMethod.DELETE, ResultModel.customerResponseMessage())//
.globalResponseMessage(RequestMethod.PUT, ResultModel.customerResponseMessage())//
.forCodeGeneration(true)//
.select()//
.apis(RequestHandlerSelectors.basePackage("com.test.springboot.example.controller"))//扫描的包
//.apis(RequestHandlerSelectors.basePackage("com.test.springboot.example.controller"))//扫描的包
.paths(PathSelectors.any())//
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")//标题
.version("1.0")//版本
.description("简单优雅的restfun风格，http://blog.csdn.net/saytime")//文档总述
.termsOfServiceUrl("http://blog.csdn.net/saytime")//
.license("222222")//
.contact("3333333")//
.build();
}
// @Api：修饰整个类，描述Controller的作用
// @ApiOperation：描述一个类的一个方法，或者说一个接口
// @ApiParam：单个参数描述
// @ApiModel：用对象来接收参数
// @ApiProperty：用对象接收参数时，描述对象的一个字段
// @ApiResponse：HTTP响应其中1个描述
// @ApiResponses：HTTP响应整体描述
// @ApiIgnore：使用该注解忽略这个API
// @ApiError ：发生错误返回的信息
// @ApiImplicitParam：一个请求参数
// @ApiImplicitParams：多个请求参数
}
访问入口配置文件
//静态资源拦截器
package com.test.springboot.config;
import com.test.springboot.util.LinusFileUtil;
import com.test.springboot.util.Log;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
/**
* @Company:wftdlx
* @Author: wjf 提示:拦截器 必须放置在一个文件中
* @Description: 拦截器类
* @Date: Created in 15:19 2018/12/19
*/
@Configuration
public class InterceptorConfig extends WebMvcConfigurationSupport {
//查询图片
//静态资源拦截 http://192.168.1.7:9091/files/文件名
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
Log.info("静态资源拦截 imageUrl ====" + LinusFileUtil.imageUrl+"静态资源拦截 projectUrl ===="+ LinusFileUtil.projectUrl);
registry.addResourceHandler("/picture/imageShow/**").addResourceLocations("file:" + LinusFileUtil.imageUrl);//自定义路径访问
registry.addResourceHandler("/picture/projectShow/**").addResourceLocations("file:" + LinusFileUtil.projectUrl);//工程路径访问
super.addResourceHandlers(registry);
//swagger2使用
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
//swagger2使用
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
4.controller层
注意必须restful风格（否则可能生成同一个接口的get，post等方法）
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
* code：数字，例如400
* message：信息，例如"请求参数没填好"
* response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
* @ApiModelProperty：描述一个model的属性
注意：@ApiImplicitParam的参数说明：
| paramType：指定参数放在哪个地方 | header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用） |
| name：参数名 | |
| dataType：参数类型 | |
| required：参数是否必须传 | true | false |
| value：说明参数的意思 | |
| defaultValue：参数的默认值 |
package com.test.springboot.example.controller;
import com.alibaba.fastjson.JSON;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.sun.org.apache.bcel.internal.generic.NEW;
import com.test.springboot.bean.ResultModel;
import com.test.springboot.example.ennity.User;
import com.test.springboot.example.mapper.UserMapper;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import netscape.security.UserTarget;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.List;
/**
* @Company:wftdlx
* @Author: wjf
* @Description:
* @Date: Created in 11:28 2019/5/13
*/
@Controller
@RequestMapping("/restful")
public class RestfulController {
@Resource
UserMapper userMapper;
// paramType：指定参数放在哪个地方：
// 1.header：请求参数放置于Request Header，使用@RequestHeader获取
// 2.query：请求参数放置于请求地址，使用@RequestParam获取
// 3.path：（用于restful接口）-->请求参数的获取：@PathVariable
// 4.body：（不常用）
// 5.form（不常用）
//查询
@ApiOperation(value = "查询一个用户详情", notes = "根据url的id来获取用户详细信息") //API 方法说明 ： value--小标题 notes--详细说明
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
// 用在方法上包含一组参数说明。 paramType:参数放在哪个地方
@GetMapping("/user/{id}") //映射地址
@ResponseBody //异步json数据
public ResultModel select(@PathVariable(name = "id") Integer id) {//@PathVariable 获取url中的变量
User user = userMapper.selectById(id);
return new ResultModel(ResultModel.SUCCESS, "查询成功", user);
}
//查询
@ApiOperation(value = "查询一个用户详情", notes = "根据入参id来获取用户详细信息") //API 方法说明 ： value--小标题 notes--详细说明
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")// 用在方法上包含一组参数说明。 paramType:参数放在哪个地方
@GetMapping("/users") //映射地址
@ResponseBody //异步json数据
public ResultModel selects(@PathVariable(name = "id") Integer id) {//@PathVariable 获取url中的变量
User user = userMapper.selectById(id);
return new ResultModel(ResultModel.SUCCESS, "查询成功", user);
}
//增加
@ApiOperation(value = "增加用户", notes = "根据入参User对象增加用户")
@ApiImplicitParam(name = "user", value = "用户对象user", required = true, dataType = "User")
@PostMapping("/user")//仅仅可以使用post方法
@ResponseBody //返回 异步json数据
public ResultModel demo1(@RequestBody User user) {//接收json请求数据；必须post请求；仅仅一个；int数据可以使用引号或者不用；对象属性不用全写；@RequestParam()可以同时使用而且可以多个
//正确结果
int insert = userMapper.insert(user);
//排错
if (insert > 0) {
return new ResultModel(ResultModel.SUCCESS, "增加成功", user);
}
return new ResultModel(ResultModel.ERROR, "增加失败", insert);
}
//删除
@ApiOperation(value = "删除一个用户", notes = "根据url的id来指定删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE, produces = "application/json;charset=UTF-8")
@ResponseBody //返回 异步json数据
public ResultModel delete(@PathVariable(name = "id") Integer id) {//接收json请求数据；必须post请求；仅仅一个；int数据可以使用引号或者不用；对象属性不用全写；@RequestParam()可以同时使用而且可以多个
int i = userMapper.deleteById(id);
//排错
if (i > 0) {
return new ResultModel(ResultModel.SUCCESS, "删除成功");
}
return new ResultModel(ResultModel.ERROR, "删除失败", i);
}
//修改
@ApiOperation(value = "修改用户", notes = "根据url的id来修改用户信息")
@ApiImplicitParam(name = "user", value = "用户对象", required = true, dataType = "User")
@RequestMapping(value = "/user", method = RequestMethod.PATCH, produces = "application/json;charset=UTF-8")
@ResponseBody //返回 异步json数据
public ResultModel patch(@RequestBody User user) {
int i = userMapper.updateById(user);
if (i > 0) {
return new ResultModel(ResultModel.SUCCESS, "修改成功", user);
} else {
return new ResultModel(ResultModel.ERROR, "修改失败", i);
}
}
/**
* 根据id修改用户信息
*
* @param user
* @return
*/
@ApiOperation(value = "修改用户", notes = "根据url的id来修改用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path"),
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
})
@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
public ResultModel update(@PathVariable("id") Integer id, @RequestBody User user) {
QueryWrapper<User> userQueryWrapper = new QueryWrapper<>();
userQueryWrapper.eq("id", id);
int update = userMapper.update(user, userQueryWrapper);
if (update > 0) {
return new ResultModel(ResultModel.SUCCESS, "修改成功", update);
} else {
return new ResultModel(ResultModel.ERROR, "修改失败", update);
}
}
}
更多精彩
