SpringBoot系列十九Springboot集成swagger

Swagger简述

Swagger 是一款RESTFUL接口的文档在线自动生成&＃43;功能测试功能软件 Swagger 是一个规范和完整的框架&＃xff0c;用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法&＃xff0c;参数和模型紧密集成到服务器端的代码&＃xff0c;允许API来始终保持同步

Spring Boot集成Swagger

本文涉及的工程&＃xff1a; swagger

pom.xml swagger需要引入如下的jar

io.springfoxspringfox-swagger22.2.2 io.springfoxspringfox-swagger-ui2.2.2

&＃64;EnableSwagger2 使用&＃64;EnableSwagger2注解在Control类上就可以swagger的功能

&＃64;RestController &＃64;EnableSwagger2 // 启动swagger注解 // api-value&＃xff1a;定义名称&＃xff0c;如果没有定义&＃xff0c;则默认显示类名 &＃64;Api(value &＃61; "Swagger Test Control", description &＃61; "演示Swagger用法的Control类", tags &＃61; "Swagger Test Control Tag") public class SwaggerTestCtl { .. }

执行启动类 执行启动类&＃xff0c;访问如下连接 http://127.0.0.1:8080/swagger-ui.html#/ 就可以进入swagger页面&＃xff0c;进行接口测试&＃xff0c;界面如下:

ApiInfo类

我们创建ApiInfo实例&＃xff0c;我们为swagger配置更多的接口说明

&＃64;Bean public Docket api() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(getApiInfo())// .pathMapping("/")// base&＃xff0c;最终调用接口后会和paths拼接在一起.select()// .paths(Predicates.or(PathSelectors.regex("/api/.*")))//过滤的接口.apis(RequestHandlerSelectors.basePackage("com.hry.swagger.ctl")) //过滤的接口.paths(PathSelectors.any()).build(); }private ApiInfo getApiInfo() {// 定义联系人信息Contact contact &＃61; new Contact("hryou0922","https://github.com/hryou0922", "hryou0922&＃64;126.com");return new ApiInfoBuilder().title("演示 Swagger 的用法") // 标题.description("演示Swagger中各种注解的用法") // 描述信息.version("1.1.2") // //版本.license("Apache 2.0").licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").contact(contact).build(); }

重启服务&＃xff0c;界面如下&＃xff1a;

swagger的注解

swagger的注解概述

我们可以使用swagger定义更详细接口说明

&＃64;Api&＃xff1a;用在类上&＃xff0c;标志此类是Swagger资源value&＃xff1a;接口说明tags&＃xff1a;接口说明&＃xff0c;可以在页面中显示。可以配置多个&＃xff0c;当配置多个的时候&＃xff0c;在页面中会显示多个接口的信息&＃64;ApiOperation&＃xff1a;用在方法上&＃xff0c;描述方法的作用&＃64;ApiImplicitParams&＃xff1a;包装器&＃xff1a;包含多个ApiImplicitParam对象列表&＃64;ApiImplicitParam&＃xff1a;定义在&＃64;ApiImplicitParams注解中&＃xff0c;定义单个参数详细信息○ paramType&＃xff1a;参数放在哪个地方§ header-->请求参数的获取&＃xff1a;&＃64;RequestHeader§ query-->请求参数的获取&＃xff1a;&＃64;RequestParam§ path&＃xff08;用于restful接口&＃xff09;-->请求参数的获取&＃xff1a;&＃64;PathVariable§ body&＃xff08;以流的形式提交仅支持POST&＃xff09;§ form&＃xff08;以form表单的形式提交仅支持POST&＃xff09;○ name&＃xff1a;参数名○ dataType&＃xff1a;参数的数据类型只作为标志说明&＃xff0c;并没有实际验证§ Long§ String○ required&＃xff1a;参数是否必须传§ true§ false○ value&＃xff1a;参数的意义○ defaultValue&＃xff1a;参数的默认值&＃64;ApiModel&＃xff1a;描述一个Swagger Model的额外信息&＃64;ApiModel用在类上&＃xff0c;表示对类进行说明&＃xff0c;用于实体类中的参数接收说明&＃64;ApiModelProperty&＃xff1a;在model类的属性添加属性说明&＃64;ApiParam&＃xff1a;用于Controller中方法的参数说明&＃64;ApiResponses&＃xff1a;包装器&＃xff1a;包含多个ApiResponse对象列表&＃64;ApiResponse&＃xff1a;定义在&＃64;ApiResponses注解中&＃xff0c;一般用于描述一个错误的响应信息○ code&＃xff1a;错误码&＃xff0c;例如400○ message&＃xff1a;信息&＃xff0c;例如"请求参数没填好"○ response&＃xff1a;抛出异常的类&＃64;Authorization Declares an authorization scheme to be used on a resource or an operation.&＃64;AuthorizationScope Describes an OAuth2 authorization scope.

##演示使用注解demo 本节我们演示上节的注解如何使用 ###&＃64;Api 用在类上&＃xff0c;标志此类是Swagger资源&＃xff0c;对接口更加详细说明

&＃64;RestController &＃64;EnableSwagger2 // 启动swagger注解 &＃64;Api(value &＃61; "Swagger Test Control", description &＃61; "演示Swagger用法的Control类", tags &＃61; "Swagger Test Control Tag") public class SwaggerTestCtl {}

结果如下:

###&＃64;ApiOperation 用在方法上&＃xff0c;描述方法的作用

// 方法的说明 &＃64;ApiOperation(value &＃61; "根据id获取记录", response &＃61; Student.class) // 定义请求参数 &＃64;ApiImplicitParams({ &＃64;ApiImplicitParam(paramType &＃61; "query", dataType &＃61; "String", name &＃61; "id", value &＃61; "主键", required &＃61; true) }) public Student queryById(String id){System.out.println("queryById id &＃61; " &＃43; id);return new Student(); }

结果如下:

&＃64;ApiImplicitParams 和 &＃64;ApiImplicitParam

// 定义请求参数 &＃64;ApiImplicitParams({ &＃64;ApiImplicitParam(paramType &＃61; "query", dataType &＃61; "String", name &＃61; "id", value &＃61; "主键", required &＃61; true) }) public Student queryById(String id){System.out.println("queryById id &＃61; " &＃43; id);return new Student(); }

结果如下:

###&＃64;ApiModel 和&＃64;ApiModelProperty

定义model类

&＃64;ApiModel( description &＃61; "学生") public class Student {&＃64;ApiModelProperty(value &＃61; "主键id")private String id;&＃64;ApiModelProperty(value &＃61; "名称", required &＃61; true)private String name;&＃64;ApiModelProperty(value &＃61; "年龄", required &＃61; true)private int age; … }

在方法使用

&＃64;RequestMapping(value &＃61; "/update", method &＃61; {RequestMethod.POST}) // 方法说明 &＃64;ApiOperation(value &＃61; "添加学生记录", notes&＃61;"传递复杂对象DTO",produces &＃61; "application/json") public int update(&＃64;RequestBody Student student){System.out.println("update student &＃61; " &＃43; student);return 1; }

结果如下:

&＃64;ApiResponses和&＃64;ApiResponse

&＃64;RequestMapping(value &＃61; "/del", method &＃61; {RequestMethod.POST, RequestMethod.GET}) // 方法说明 &＃64;ApiOperation(value &＃61; "删除学生记录学生记录") // 定义返回值意义 &＃64;ApiResponses({&＃64;ApiResponse(code &＃61; 400, message &＃61; "服务器内部异常"),&＃64;ApiResponse(code &＃61; 500, message &＃61; "权限不足") }) public int del(int id){System.out.println("del id &＃61; " &＃43; id);return 1; }

结果如下: