Swagger作用
在前后端分离中,API接口文档的纽带作用显得尤为重要。后端甩给前端一份接口文档,前端就知道传入参数的方法、参数类型、以及返回类型。Swagger的作用就是你不必手写接口文档,并且后端在写完接口后还能用swagger进行测试,可谓一举三得。
**使用springboot 2.0.0
整合 swagger2.9**
1. 新建Springboot项目,并引入swagger依赖
<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.0</version>
</dependency>
两个依赖的作用
springfox-swagger2
依然是依赖OSA
规范文档,也就是一个描述API
的json
文件,而这个组件的功能就是帮助我们自动生成这个json
文件,
springfox-swagger-ui
就是将这个json
文件解析出来,用一种更友好的方式呈现出来。
2. 配置Swagger2
在springboot
启动类同级目录中创建Swagger2
的配置文件
package me.hong.icarus;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
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;
/**
* swagger2
* 地址栏输入如下:
* http://localhost:9092/swagger-ui.html#
*/
@Configuration
@EnableSwagger2
public class Swagger2 implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/static/**")
.addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
@Bean
public Docket createRestApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("Rest Api")
.description("Just once that all I need")
.termsOfServiceUrl("http://www.icarus.com")
.contact(new Contact("擎天柱", "", "gg.hilock@gmail.com"))
.version("1.0.0")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("me.hong.icarus"))
.paths(PathSelectors.any())
.build();
}
}
编写Controller
package me.hong.icarus.user.controller;
import com.alibaba.dubbo.config.annotation.Reference;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import me.hong.icarus.user.model.User;
import me.hong.icarus.user.rest.service.UserService;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.web.bind.annotation.*;
@RestController
@RefreshScope
@RequestMapping(value = "/icarus/icarus")
public class UserController {
@Reference
UserService userService;
@ApiOperation(value = "通过id获取用户",httpMethod = "GET")
@ApiImplicitParams(value = {})
@GetMapping(value = "/user/get_id/{id}")
public User getUserById(@PathVariable("id") String id) {
try {
return userService.getUserById(id);
} catch (Exception e) {
e.printStackTrace();
throw e;
}
}
}
浏览器打开Swagger2API文档
在地址栏输入:http://localhost:9092/swagger-ui.html#
。其中9092是项目端口号。
在实际使用中,应该了解关于Swagger2的具体注解的参数说明,这个很基础也很重要。
网友评论