使用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