SpringBoot搭建Swagger

   如何在大公司中使用前后端分离时，后台人员需要写接口文档，如果项目搭建过程，搭建了Swagger这个插件，就很方便，不用自己编写接口文档，不用自己用Postman工具去浪费时间，接口更新后不需要再重新写接口文档SpringBoot.

SpringBoot整合Swagger基本步骤

1. 在pom配置文件中加入依赖

    1)如果是SpringBoot项目，就直接加入下面这个配置

  <!-- swagger-spring-boot -->
		 <dependency>
			<groupId>com.spring4all</groupId>
			<artifactId>swagger-spring-boot-starter</artifactId>
			<version>1.7.0.RELEASE</version>
		 </dependency>

   2)如何不是SpringBoot项目，加入下面依赖可以

<!-- Swagger接口API配置 -->
			<dependency>
				<groupId>io.springfox</groupId>
				<artifactId>springfox-swagger2</artifactId>
				<version>2.8.0</version>
			</dependency>

		  <dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.8.0</version>
		</dependency>

2.编写Swagger配置类 

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;

/**
 * @author zh
 * @ClassName cn.saytime.Swgger2
 * @Description
 * @date 2017-07-10 22:12:31
 */
@Configuration
public class Swagger2 {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("cn.saytime.web"))
     //这个就是自己的控制层，所有的接口包，来扫描包
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("springboot利用swagger构建api文档")
				.description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
				.termsOfServiceUrl("http://blog.csdn.net/saytime")
				.version("1.0")
				.build();
	}
}

3. 在启动主程序中加入 @EnableSwagger2注解

@SpringBootApplication
@MapperScan("com.zhongjin.annualmeeting.dao")
@ServletComponentScan("com.zhongjin.annualmeeting.filter")
@ComponentScan(basePackages = { "com.zhongjin.annualmeeting" })
@EnableSwagger2
public class AnnualmeetingApplication {

	public static void main(String[] args) {
		SpringApplication.run(AnnualmeetingApplication.class, args);
	}

}

 

4.访问swagger.ui页面，查看文档API

在浏览器中输入： http：// 自己项目地址/ swagger-ui.html，就可以查看文档

举个栗子：输入： http://localhost:8050/annualmeeting/swagger-ui.html#/

结果视图：这就是自己项目下所有的接口，在这个上面就可以测试自己的接口

 

 

 

如果想让自己的接口说明更加清楚，通过这些注释在control层进行添加就可以

Swagger使用的注解及其说明：

@Api：用在类上，说明该类的作用。一般用在control接口类上，进行接口分分组

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

    l   code：数字，例如400

    l   message：信息，例如"请求参数没填好"

    l   response：抛出异常的类   

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

    l   @ApiModelProperty：描述一个model的属性

 

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值