Swagger 教程

SpringBoot与Swagger2整合

---

• 依赖：

<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-web</artifactId>
	</dependency>
	<dependency>
		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.9.2</version>
	</dependency>
	<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.9.2</version>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
		<exclusions>
			<exclusion>
				<groupId>org.junit.vintage</groupId>
				<artifactId>junit-vintage-engine</artifactId>
			</exclusion>
		</exclusions>
	</dependency>
</dependencies>

• SwaggerConfig：

package com.blu.config;

import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	public static final Contact BLU_CONTACT = new Contact("BLU", "http://localhost:8080", "[e-mail]");
	
	/**
	 * 配置了Swagger的Docket的bean实例
	 */
	@Bean
	public Docket docket(Environment environment) {
		
		//设置需要启动Swagger的环境
		Profiles profiles = Profiles.of("dev","test");
		//通过acceptsProfiles方法判断是否处于指定的环境中
		boolean flag = environment.acceptsProfiles(profiles);
		
		
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				//是否启动Swagger，默认为true，这里通过flag来确保在开发环境启动，在发布环境关闭
				.enable(flag)
				//设置分组名，（通过创建不同的 Docket Bean 来实现分组）
				.groupName("BLU组")
				.select()
				//配置扫描接口的方式,basePackage指定要扫描的包
				.apis(RequestHandlerSelectors.basePackage("com.blu.controller"))
				//依据指定的注解来扫描
				//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				//指定扫描的url
				//.paths(PathSelectors.ant("/hello/**"))
				.build();
	}
	
	@Bean
	public Docket docketA() {
		return new Docket(DocumentationType.SWAGGER_2).groupName("A组");
	}
	
	/**
	 * 自定义apiInfo
	 */
	private ApiInfo apiInfo() {
		return new ApiInfo(
				"BLU的SwaggerApi文档",
				"即使再小的帆也能远航",
				"1.0",
				"http://localhost:8080",
				BLU_CONTACT,
				"Apache 2.0",
				"http://www.apache.org/licenses/LICENSE-2.0",
				new ArrayList()
		);
	}

}

• application.properties

spring.profiles.active=dev

• application-dev.properties

server.port=8080

• application-pro.properties

server.port=8081

• User实体类：

package com.blu.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("用户实体类")
public class User {

	@ApiModelProperty("用户ID")
	private int id;
	@ApiModelProperty("用户名")
	private String username;
	@ApiModelProperty("年龄")
	private int age;
	
	public int getId() {
		return id;
	}
	public void setId(int id) {
		this.id = id;
	}
	public String getUsername() {
		return username;
	}
	public void setUsername(String username) {
		this.username = username;
	}
	public int getAge() {
		return age;
	}
	public void setAge(int age) {
		this.age = age;
	}
	
	
}

• HelloController

package com.blu.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.blu.entity.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

@Api(tags="HelloController控制类")
@RestController
public class HelloController {

	@ApiOperation("HelloController控制类中的Hello()方法")
	@RequestMapping(value="/hello")
	public String Hello() {
		return "hello";
	}
	
	@ApiOperation("HelloController控制类中的user()方法")
	@PostMapping("/user")
	public User user() {
		return new User();
	}
	
	@ApiOperation("HelloController控制类中的Hello2()方法")
	@GetMapping("/hello2")
	public String Hello2(@ApiParam("Hello2()方法中的username参数") @RequestParam String username) {
		return "hello"+username;
	}
	
}

• 启动类：

package com.blu;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringbootSwaggerApplication {

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

}

• 启动后，访问：http://localhost:8080/swagger-ui.html

BLU组：

A组：

接口测试示例：