背景介绍:
Swagger是一个用于java代码中写注解,然后可以通过访问指定的网页,自动生成接口文档,并且可以通过接口进行功能测试。
使用介绍:
(1)添加Maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
(2)Java代码中设置Swagger2Confg.java
package com.example.demo;
import com.fasterxml.classmate.TypeResolver;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.ResponseEntity;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.lang.reflect.WildcardType;
import static springfox.documentation.schema.AlternateTypeRules.newRule;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Autowired
private TypeResolver typeResolver;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
.paths(PathSelectors.any())
.build()
.alternateTypeRules(
newRule(typeResolver.resolve(Result.class,
typeResolver.resolve(ResponseEntity.class, WildcardType.class)),
typeResolver.resolve(WildcardType.class))
)
;
}
/**
* 创建该API的基本信息(这些基本信息会展现在文档页面中)
* 访问地址:http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多请关注http://www.baidu.com")
.termsOfServiceUrl("http://www.baidu.com")
.contact("sunf")
.version("1.0")
.build();
}
}
(4)api接口调用示例
package com.example.demo;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
@RestController
@Api(value = "DemoController | 一个用来测试swagger注解的控制器")
public class DemoController {
public String getUserByGet() {
return "1";
}
/**
* get方法demo
*
* @param userId
* @return
*/
@ApiOperation(value = "根据id获取用户信息(Get方法)")
@ApiImplicitParam(paramType = "query", name = "userId", value = "用户id", required = true, dataType = "Integer")
@GetMapping("/getUser")
public String getUserByGet(Integer userId) {
return "success" + userId;
}
/**
* get pathVariable demo
*
* @param userId
* @return
*/
@ApiOperation(value = "根据id获取用户信息(PathVariable方法)", notes = "仅1和2返回正确信息", httpMethod = "GET")
@GetMapping("/getUser/{userId}")
public String getUserByPathVariable(@ApiParam(name = "userId", value = "用户id", required = true) @PathVariable Integer userId) {
if (userId == 1 || userId == 2) {
return "success" + userId;
} else {
return "error";
}
}
/**
* post 传入json数据 demo
*
* @param user
* @return
*/
@ApiOperation(value = "插入用户数据", notes = "用json数据插入")
@PostMapping("/insertUser")
public Result<User> insetUser(@RequestBody @ApiParam(name = "用户对象", value = "传入json格式", required = true) User user) {
Result result = new Result();
result.setCode(200);
result.setData(user);
return result;
}
}
(5)成功加载的效果图如下
(6)如果觉得上面的uri不好看的话,可以用如下的包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>0.0.2</version>
</dependency>
参考文档: