springboot项⽬配置swagger2⽰例详解
swagger简介
Swagger是⼀款RESTful接⼝的⽂档在线⾃动⽣成、功能测试功能框架。⼀个规范和完整的框架，⽤于⽣成、描述、调⽤和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。
当我们在后台的接⼝修改了后，swagger可以实现⾃动的更新，⽽不需要⼈为的维护这个接⼝进⾏测试。
⼀、swagger2中常⽤的注解作⽤
注解作⽤
@Api修饰整个类，描述Controller的作⽤，表⽰标识这个类是swagger的资源
@ApiOperation描述⼀个类的⼀个⽅法，或者说⼀个接⼝，表⽰⼀个http请求的操作
@ApiParam⽤于⽅法的参数，表⽰对参数的添加元数据
@ApiModelProperty⽤于⽅法，字段。表⽰对model属性的说明或者数据操作更改
⼆、springboot项⽬配置swagger2步骤
1、springboot项⽬的⽬录结构如下：
2、l⽂件引⼊如下配置
<!--引⼊web相关依赖-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--引⼊swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--引⼊swagger-ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
3、l配置⽂件配置如下
server:
port: 8001 #端⼝
servlet:
context-path: /springSecurity #配置项⽬名称
4、Swagger配置⽂件如下：
fig;
lemon.base.Predicate;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import t.annotation.Bean;
import t.annotation.Configuration;
import org.springframework.http.ResponseEntity;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import lemon.;
import static springfox.documentation.;
/**
* @description: Swagger配置⽂件
* @author: xz
*/
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
//注⼊配置⽂件中的项⽬名称
@Value("${t-path}")
private String contextPath;
/**
* 构建 swagger2 api ⽂档的详细信息函数
* @return
*/
private ApiInfo initApiInfo() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("springSecurity测试项⽬ Platform API")//⼤标题
.version( "1.0.0")//版本
.description(initContextInfo())//描述
.contact(new Contact("xz", "wwwxz.blog.csdn/", "123456@qq"))//作者信息
.license("The System Server, Version 1.0")//⽹站链接显⽰⽂字
.licenseUrl("wwwxz.blog.csdn/")//⽹站链接
.build();
return apiInfo;
}
private String initContextInfo() {
StringBuffer sb = new StringBuffer();
sb.append("REST API 设计在细节上有很多⾃⼰独特的需要注意的技巧，并且对开发⼈员在构架设计能⼒上⽐传统 API 有着更⾼的要求。")
.append("<br/>")
.append("本⽂通过翔实的叙述和⼀系列的范例，从整体结构，到局部细节，分析和解读了为了提⾼易⽤性和⾼效性，REST API 设计应该注意哪些问题以及如何解决这些问题。"); String();
}
/**
* swagger2的配置⽂件，这⾥可以配置swagger2的⼀些基本的内容，⽐如扫描的包等等
* @return
*/
@Bean
public Docket restfulApi() {
System.out.println("localhost:8001" + contextPath + "/swagger-ui.html");
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(initApiInfo())
.groupName("RestfulApi")
//.genericModelSubstitutes(DeferredResult.class)
.genericModelSubstitutes(ResponseEntity.class)
.useDefaultResponseMessages(true)
.forCodeGeneration(false)
.pathMapping(contextPath) // base，最终调⽤接⼝后会和paths拼接在⼀起
.select()
/
/加了ApiOperation注解的类，才⽣成接⼝⽂档
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//暴露接⼝地址的包路径（即此包下的类，才⽣成接⼝⽂档）
.apis(RequestHandlerSelectors.basePackage("ller"))
.paths(doFilteringRules())//⾃定义的过滤规则
.build();
}
/**
* 设置过滤规则
* 这⾥的过滤规则⽀持正则匹配
* @return
*/
private Predicate<String> doFilteringRules() {
return or(
regex("/testUser.*"),
regex("/hello.*")
);
}
}
5、⽤户实体类如下：
ity;
import io.swagger.annotations.ApiModelProperty;
/
**
* @description: ⽤户实体类
* @author: xz
*/
public class UserQueryCondition {
private int id;
@ApiModelProperty(value = "⽤户名称")
private String name;
private int age;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public int getAge() {
return age;
}
public void setAge(int age) {
this.age = age;
}
}
6、控制层代码如下：
ller;
ity.User;
ity.UserQueryCondition;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.apachemons.lang.builder.ReflectionToStringBuilder;
import org.apachemons.lang.builder.ToStringStyle;
import org.springframework.web.bind.annotation.*;
/**
* @description: 控制层代码如下
* @author: xz
*/
@Api(value = "API - UserController",description = "⽤户模块接⼝详情")
@RestController
@RequestMapping("/testUser")
public class UserController {
/***
* @ApiParam 如果⽅法接受的是具体参数，此注解需要加到⽅法中的参数上
*/
@RequestMapping(value = "/queryUserByName",method = RequestMethod.GET)
@ApiOperation(value = "根据⽤户名称查询服务")
public void queryUserByName(@ApiParam(value = "⽤户username") @RequestParam(name="username",required = false, defaultValue ="tom" ) String name){ System.out.println("queryUser====="+name);
}
/***
springboot框架的作用* @ApiOperation 可⽤在⽅法头上.参数的描述容器
* @ApiModelProperty 如果⽅法接受的是实体，此注解需要加到实体的具体属性上
*/
@RequestMapping(value = "/queryUserAll",method = RequestMethod.GET)
@ApiOperation(value = "根据⽤户id、名称和年龄查询服务")
public void queryUserAll(UserQueryCondition userQueryCondition){
//利⽤反射⼯具把对象输出
System.out.String(userQueryCondition, ToStringStyle.MULTI_LINE_STYLE));
}
/***
* @ApiOperation 可⽤在⽅法头上.参数的描述容器
*/
@PostMapping(value = "/createUser")
@ApiOperation(value = "⽤户新增服务")
public User userCreate1(@RequestBody User user){
System.out.Name()+"----"+Password());
user.setId(1);
return user;
}
/***
* @ApiOperation 可⽤在⽅法头上.参数的描述容器
*/
@PutMapping("/{id:\\d+}")
@ApiOperation(value = "⽤户修改服务")
public User update(@RequestBody User user){
System.out.Id()+"======"+Name()+"----"+Password());
user.setId(1);
return user;
}
/***
* @ApiOperation 可⽤在⽅法头上.参数的描述容器
*/
@DeleteMapping("/{id:\\d+}")
@ApiOperation(value = "⽤户删除服务")
public void delete(@PathVariable String id){
System.out.println(id);
}
}
7、启动项⽬，如下图：
9、点击user-Controller，如下图所⽰：
10、点击具体某⼀⽅法，可以看到如下信息：
三、⽰例中使⽤的注解解析
1、@Api注解标注在了控制层的UserController类上，如下图画红⾊框的位置可以看到注解⽣效。
2、@ApiOperation注解标注在了控制层的UserController类的⽅法上，如下图画红⾊框的位置可以看
到注解⽣效。
3、@ApiParam注解标注在了控制层的⽅法参数上，如下图画红⾊框的位置可以看到注解⽣效。
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论