使用swagger不用手工写API相关的word文档了,并且还可以使用swagger生成的API文档进行测试,使用起来倍儿爽。接下来咱们就来搞一个demo案例。
先是pom.xml引用和版本:
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.8.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.lawt</groupId>
<artifactId>swagger-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>swagger-demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
</dependencies>
springboot启动类:
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerDemoApplication.class, args);
}
}
swagger相关扫描和配置:
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
//扫描路径
private final String SWAGGER_SCAN_BASE_PACKAGE
= "com.lawt.swaggerdemo.controller";
//开关
@Value("${swagger.enable}")
private Boolean enable;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(enable)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("我的swagger demo API")
.version("1.0.0")
.build();
}
}
一个controller类:
import com.lawt.swaggerdemo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@RestController
@Api(description = "用户信息操作")
public class UserController {
@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
@GetMapping("/user/{id}")
public User getUserById(@PathVariable("id") Integer id) {
return new User(10001, "lawt");
}
}
实体类User:
import io.swagger.annotations.ApiModelProperty;
public class User {
@ApiModelProperty(value = "用户id")
private Integer userId;
@ApiModelProperty(value = "用户名称")
private String userName;
public User(Integer userId, String userName) {
this.userId = userId;
this.userName = userName;
}
//get set method .....
}
配置项:
server.port=8801
#如果线上环境不需要swagger功能,需要改成false
swagger.enable=true
启动,并访问:
http://127.0.0.1:8801/swagger-ui.html
页面显示:
点击 Show/Hide
点击右边的 获取用户详细信息
输入参数
点Try it out!
显示 linux环境下怎么请求改接口,请求参数、返回参数等信息。
Ok,自此demo已经搞定,swagger远不止这些功能。
可以参考:
官网:https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview 其他参考网址: https://blog.csdn.net/u014231523/article/details/76522486