Swagger 简介#
现在很容易通过spring boot来实现一个rest api为服务，但是当服务直接进行接口相互调用时就需要提供相应的接口，Swagger可以很方便的通过注解的方式 生成对应的API接口文档，易于维护和spring boot有很好的集成。同时Swagger提供了swagger-ui来可以交互式的演示你的接口调用。
Swagger 配置#
- 依赖配置 如果你使用的是Maven那么需要添加如下依赖
<code><dependency>
<groupid>io.springfox/<groupid>
<artifactid>springfox-swagger2/<artifactid>
<version>2.9.2/<version>
<scope>compile/<scope>
/<dependency>
<dependency>
<groupid>io.springfox/<groupid>
<artifactid>springfox-swagger-ui/<artifactid>
<version>2.9.2/<version>
<scope>compile/<scope>
/<dependency>/<code>
如果你使用的是Gradle那么需要添加如下依赖
<code>\tcompile "io.springfox:springfox-swagger2:2.9.2"
\tcompile "io.springfox:springfox-swagger-ui:2.9.2"/<code>
如果你使用的是Spring boot那么默认已经集成了web页面访问的功能只需增加Swagger的Configuration即可, 否则需要继承WebMvcConfigurationSupport,然后重写ResourceHandler保证页面可以正常访问
<code> @Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}/<code>
<code>import com.google.common.base.Predicate;
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.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
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;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket postsApi() {
return new Docket(DocumentationType.SWAGGER_2) //这里配置Swagger
.groupName("public-api")
.apiInfo(apiInfo())
.select()
.paths(postPaths())
.build();
}
private Predicate<string> postPaths() { //这里选择要过滤的请求
return or(
regex("/person.*")
);
}
private ApiInfo apiInfo() { //这里显示Swagger的描述信息
return new ApiInfoBuilder()
.title("Upscale API")
.description("Upscale API reference for developers")
.termsOfServiceUrl("http://springfox.io")
.contact(new Contact("Jet Qin","http://jetqin.github.io","[email protected]"))
.license("Apache License Version 2.0")
.licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")
.version("2.0")
.build();
}
}/<string>/<code>
配置API接口#
配置完基本的Swagger之后可以开始配置Rest API接口，实现接口时建议最好使用 GetMapping,PutMapping,PostMapping,DeleteMapping等注解来代替RequestMapping RequstMapping会同时支持多种http方法，产生的接口会重复，所有通过method来限制。
- 配置Controller
Swagger提供了Api注解来描述Controller同时还提供了一些其他信息的配置，可参考io.swagger.annotations.Api @Api(value="person manager", tags={"Operations for person"})
- 配置RequestMapping 定义接口的时候最好根据需要使用不同的http method来进行限制， 通过@ApiOperation可以对接口功能进行 描述，定义返回结果的类型。默认的Swagger提供了对多种http返回结果的默认描述如Http 200, 401, 500等 我们可以通过@ApiResponse来自定义这些返回结果的描述。
<code>@RestController
@RequestMapping("/person")
@Api(value="person manager", tags={"Operations for person"})
public class PersonController {
@Autowired
PersonService service;
@DeleteMapping
@GetMapping(value="/list",produces = "application/json")
@ApiOperation(value = "View a list of available person", response = Person.class)
@ApiResponses({
@ApiResponse(code = 200, message = "Successfully retrieve person"),
@ApiResponse(code = 401, message = "You are not authorized to view the resource"),
@ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
@ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
})
public List<person> listPerson(){
return service.listPerson();
}
}/<person>/<code>
效果演示#
通过swagger-ui页面的execute按钮可以访问对应的接口并返回相应的结果。
返回结果
分享到:
閱讀更多 JetQin90 的文章
