spring boot集成swagger构建API文档

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


上一篇:php实现微信模板消息推送


下一篇:微信小程序 上传图片