Swagger使用
spring boot下建议使用:
一.使用第三方依赖
https://github.com/SpringForAll/spring-boot-starter-swagger
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.1.RELEASE</version>
</dependency>
在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解,就可以直接使用啦。
https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目,里面有详细的讲解。
1. Swagger UI
按以下步骤配置,项目启动后访问:
http://localhost:8080/swagger-ui.html
二.使用官方依赖
1.1 添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
1.2 配置类
@Configuration
@EnableSwagger2
public class Swagger2 extends WebMvcConfigurationSupport implements EnvironmentAware{
public static final String SWAGGER_SCAN_BASE_PACKAGE = "abc.boot.examples.web";
public static final String VERSION = "1.0.0";
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//api接口包扫描路径
.paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档,忽略哪些请求
.build();
}
//Spring Boot自动配置本身不会自动把/swagger-ui.html这个路径映射到对应的目录META-INF/resources/下面。我们加上这个映射即可。
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars*")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2 接口文档示例")//设置文档的标题
.description("更多内容请关注:http://www.abc.com")//设置文档的描述->1.Overview
.version(VERSION)//设置文档的版本信息-> 1.1 Version information
.contact(new Contact("ABC Boot", "http://www.abc.comt", ""))//设置文档的联系方式->1.2 Contact information
.termsOfServiceUrl("www.abc.com")//设置文档的License信息->1.3 License information
.build();
}
}
1.3 注解使用
@ApiOperation
@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")
@RequestMapping(value="/users", method= RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}
@ApiResponses
@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",produces = "application/json")
// ApiResponses 增加返回结果的描述
@ApiResponses(value = {@ApiResponse(code = 405,message = "Invalid input",response = Integer.class)}) (1)
@ApiImplicitParam(name = "id",value = "用户ID",dataType = "int",paramType = "path") (2)
@RequestMapping(value="/users/{id}", method= RequestMethod.GET)
public User getUser(@PathVariable Integer id) {
return users.get(id);
}
(1) 在默认Response的基础上增加新的Response说明
(2) 使用ApiImplicitParam描述接口参数
@ApiImplicitParams
@ApiOperation(value="更新用户名称", notes="更新指定用户的名称")
@RequestMapping(value="/users/{id}", method= RequestMethod.POST)
@ApiImplicitParams({ (1)
@ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"), (2)
@ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
public void updateUserName(@PathVariable Integer id,@Reque