springboot+swagger2说明

Posted 2022-12-01 stubbornness1219

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了springboot+swagger2说明相关的知识，希望对你有一定的参考价值。

swagger用于定义API文档。

优势：

前后端分离开发
API文档非常明确
测试的时候不需要再使用URL输入浏览器的方式来访问Controller
传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件

添加pom依赖

<!--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-->

Swagger2Config初始化配置如下： [java] view plain copy

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());

Controller中测试方法：
在这里我们使用@ApiOperation注解来声明此方法为要生成的接口文档，在配置中已经配置过了，如果不想方法生成文档，不加此注解即可；配置中已经使用了自定义的响应信息，所以可以不设置@ApiResponses；
[java] view plain copy

@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：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
- code：数字，例如400
- message：信息，例如"请求参数没填好"
- response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
- @ApiModelProperty：描述一个model的属性