本文主要是介绍springboot+swagger2说明,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!
swagger用于定义API文档。
优势:
- 前后端分离开发
- API文档非常明确
- 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
- 传统的输入URL的测试方式对于post请求的传参比较麻烦(当然,可以使用postman这样的浏览器插件
<!--swagger2 start--> <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> <!--swagger2 end-->
- package com.gasq.travel.config;
- import com.gasq.travel.common.CodeEnum;
- import com.gasq.travel.utils.collections.ListUtils;
- import io.swagger.annotations.ApiOperation;
- import org.springframework.beans.factory.annotation.Value;
- import org.springframework.boot.context.properties.ConfigurationProperties;
- import org.springframework.context.annotation.Bean;
- import org.springframework.context.annotation.Configuration;
- import org.springframework.web.bind.annotation.RequestMethod;
- import org.springframework.web.context.request.async.DeferredResult;
- import springfox.documentation.builders.ApiInfoBuilder;
- import springfox.documentation.builders.PathSelectors;
- import springfox.documentation.builders.RequestHandlerSelectors;
- import springfox.documentation.builders.ResponseMessageBuilder;
- import springfox.documentation.schema.ModelRef;
- import springfox.documentation.service.ApiInfo;
- import springfox.documentation.service.ResponseMessage;
- import springfox.documentation.spi.DocumentationType;
- import springfox.documentation.spring.web.plugins.Docket;
- import springfox.documentation.swagger2.annotations.EnableSwagger2;
- import java.util.List;
- /**
- * @description: swagger2配置文件类
- * @访问路径: 如 http://localhost:8080/swagger-ui.html
- * @author fanpeng
- * @create 2017-01-03 10:00
- * @Modify By:
- **/
- @Configuration
- @EnableSwagger2
- @ConfigurationProperties
- public class Swagger2Config {
- @Value("${swagger.version}") private String version;
- @Value("${swagger.basePackage}") private String basePackage;
- @Bean
- public Docket createRestApi() {
- return new Docket(DocumentationType.SWAGGER_2)
- .apiInfo(apiInfo())
- .groupName("travel")
- .genericModelSubstitutes(DeferredResult.class)
- .useDefaultResponseMessages(false)
- .globalResponseMessage(RequestMethod.GET,customerResponseMessage())
- .forCodeGeneration(true)
- .select()
- .apis(RequestHandlerSelectors.basePackage(basePackage))
- .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
- .paths(PathSelectors.any())
- .build();
- }
- private ApiInfo apiInfo() {
- return new ApiInfoBuilder()
- .title("国安社区-travel接口")
- .description("I'm description..")
- .contact("东哥")
- .version(version)
- .license("国安社区")
- .licenseUrl("baidu.com")
- .build();
- }
- /**
- * 自定义返回信息
- * @param
- * @return
- */
- private List<ResponseMessage> customerResponseMessage(){
- return ListUtils.convertToList(
- new ResponseMessageBuilder()//500
- .code(CodeEnum.error.getValue())
- .message(CodeEnum.error.getDescription())
- .responseModel(new ModelRef("Error"))
- .build(),
- new ResponseMessageBuilder()//401
- .code(CodeEnum.paramError.getValue())
- .message(CodeEnum.paramError.getDescription())
- .build());
- }
- }
- @ApiOperation(value="测试日志程序", notes="测试日志程序", produces = "application/json")
- @ApiImplicitParams(value = {
- @ApiImplicitParam(name = "school", value = "学校名称", required = true, paramType = "query", dataType = "String"),
- @ApiImplicitParam(name = "name", value = "姓名", required = true, paramType = "query", dataType = "String")
- })
- @RequestMapping(value = "/get",method = RequestMethod.GET)
- public void testProgram(HttpServletRequest request, HttpServletResponse response){
- logger.debug("debug");
- logger.info("info");
- logger.error("error");
- logger.warn("warn");
- Student student = studentCommandService.selectById(1);
- // Student student = studentCommandService.queryById(1l);
- System.out.println(student.toString());
- this.renderJson(CodeEnum.success.getValue(),CodeEnum.success.getDescription(),student,request,response);
- }
注解说明:
- @Api:用在类上,说明该类的作用
- @ApiOperation:用在方法上,说明方法的作用
- @ApiImplicitParams:用在方法上包含一组参数说明
- @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
- paramType:参数放在哪个地方
- header-->请求参数的获取:@RequestHeader
- query-->请求参数的获取:@RequestParam
- path(用于restful接口)-->请求参数的获取:@PathVariable
- body(不常用)
- form(不常用)
- name:参数名
- dataType:参数类型
- required:参数是否必须传
- value:参数的意思
- defaultValue:参数的默认值
- paramType:参数放在哪个地方
- @ApiResponses:用于表示一组响应
- @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
- code:数字,例如400
- message:信息,例如"请求参数没填好"
- response:抛出异常的类
- @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
- @ApiModelProperty:描述一个model的属性
需要注意的是:
- ApiImplicitParam这个注解不只是注解,还会影响运行期的程序,例子如下:
如果ApiImplicitParam中的phone的paramType是query的话,是无法注入到rest路径中的,而且如果是path的话,是不需要配置ApiImplicitParam的,即使配置了,其中的value="手机号"也不会在swagger-ui展示出来。
具体其他的注解,查看:
https://github.com/swagger-api/swagger-core/wiki/Annotations#apimodel
生成文档效果: 果完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html,就能看到上文所展示的RESTful API的页面。
这篇关于springboot+swagger2说明的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!