最新要闻

广告

手机

iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?

iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?

警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案

警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案

家电

SpringBoot整合Swagger2在线文档

来源:博客园

SpringBoot整合Swagger2在线文档

一 什么是swagger?

我们前面有讲到说开发时会创建Restful风格的API接口,供第三方或前端人员使用,那么前端人员在使用的过程中怎么知道有哪些接口呢。这个时候可以通过写接口文档来解决,但不同的程序员写出来的可能不一样,前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。如果能有工具帮我们能规范接口文档,最好能自动帮我们生成接口文档就好了。于是生成在线文档的工具就是 swagger就产生了。

1、什么是Swagger ?

Swagger是一款开源工具,依据OpenAPI规范(OpenAPI Specification,简称OAS)可以帮助你设计,构建,生成文档,调用REST APIs。

2、Swagger优点

1.号称世界上最流行的Api框架;2.RestFul Api 文档在线自动生成工具,Api文档与Api定义同步更新(写完代码文档就实时更新)3.可以直接运行,可以在线测试Api接口;4.支持多种语言(java,php等)

二 Springboot中怎么整合Swagger2

Swagger工具既然这么好用,那么我们就来看一下在SpringBoot中怎么整合Swagger。


(资料图)

Swagger的工具很多,但SpringBoot中整合Swagger主要是使用Swagger来构建强大的Restful文档。也就是里面的Swagger UI工具。

这里我们用的版本是Swagger2。

1.创建Springboot项目

选择web、 lombok、 mysql、spring data jpa 依赖 (也可以将spring data jpa 换成mybatis相关依赖)

项目创建成功后在pom文件中添加druid依赖包

完成后pom文件如下:

            org.springframework.boot        spring-boot-starter-data-jpa                org.springframework.boot        spring-boot-starter-web                mysql        mysql-connector-java                5.1.45        runtime                com.alibaba        druid-spring-boot-starter        1.1.10                  org.projectlombok        lombok        true                org.springframework.boot        spring-boot-starter-tomcat        provided                org.springframework.boot        spring-boot-starter-test        test    

添加数据库配置信息:

# 数据库的基本配置spring.datasource.driver-class-name=com.mysql.jdbc.Driverspring.datasource.username=rootspring.datasource.password=rootspring.datasource.url=jdbc:mysql://localhost:3306/boot1?characterEncoding=utf8&serverTimezone=GMT%2B8#配置连接池spring.datasource.type=com.alibaba.druid.pool.DruidDataSource# JPA配置spring.jpa.database=mysql# 是否在控制台打印SQLspring.jpa.show-sql=truespring.jpa.hibernate.ddl-auto=update# 指定默认的存储引擎为InnoDB,默认情况下,自动创建表的时候会使用 MyISAM 做表的引擎,# 如果配置了数据库方言为 MySQL57Dialect,则使用 InnoDB 做表的引擎。spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL57Dialect

2.创建Restful风格的Api

​ 结构图如下:

User类:

package com.example.swagger.pojo;import io.swagger.annotations.ApiModel;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;import javax.persistence.*;@Data@NoArgsConstructor@AllArgsConstructor@Entity@Table(name = "users")public class User {    @Id    @GeneratedValue(strategy = GenerationType.IDENTITY)    private int id;    private String uname;    private int age;}

UserRepository类:

package com.example.swagger.dao;import com.example.swagger.pojo.User;import org.springframework.data.jpa.repository.JpaRepository;public interface UserRepository  extends JpaRepository {}

这里省略了service层,直接在控制层里调用dao层

userController类:

package com.example.swagger.controller;import com.example.swagger.dao.UserRepository;import com.example.swagger.pojo.User;import com.example.swagger.util.Response;import com.example.swagger.util.ResponseResult;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RestController;import java.util.List;@RestControllerpublic class UserController {    @Autowired    private UserRepository userRepository;    //查询所有    @GetMapping("/users")    public ResponseResult> selectUsers()    {         List usersList= userRepository.findAll();         return Response.createOkResp(usersList);    }    //根据id查询    @GetMapping("/users/{id}")    public ResponseResult selectUserById(@PathVariable(name = "id") int id)    {         User user= userRepository.findById(id).get();         return Response.createOkResp(user);    }    //添加    @PostMapping("/users")    public ResponseResult addUser(User user)    {        userRepository.save(user);        return Response.createOkResp("add success");    }}

3.添加Swagger2

3.1添加相关jar包

    io.springfox    springfox-swagger2    2.9.2    io.springfox    springfox-swagger-ui    2.9.2

3.2 开启Swagger

swagger2 在springboot框架中使用需要 开启 @EnableSwagger2, 同时它支持自定义ui页面的一些信息

3.3 查看在线文档页

设置上面两个步骤后,打开 http://localhost:8080/swagger-ui.html

就可以看到接口信息

3.4 配置 Docket(可选)

我们把一个Docket类的一个实例添加到Spring的 BeanFactory中,以实现Swagger页面一些展示信息的定制化,例如作者,标题,描述等信息,也可以进行一些响应的配置项,例如扫描的Controller类基础包名等等。swagger会在初始化时从Spring的 BeanFactory中获取该实例(如果没有则使用默认的Docket实例),来完成初始化。

package com.example.swagger.config;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;@Configurationpublic class Swagger2 {    @Bean    public Docket docket() {        return new Docket(DocumentationType.SWAGGER_2).apiInfo(                new ApiInfoBuilder()                        .contact(new Contact("daimenglaoshi", "", "2398779723@qq.com"))                        .title("SpringBoot整合Swagger2")                        .build()        );    }}

上面是对Docket进行一个非常简单的配置。效果如图

3.5 给Api接口添加注解

package com.example.swagger.controller;import com.example.swagger.dao.UserRepository;import com.example.swagger.pojo.User;import com.example.swagger.util.Response;import com.example.swagger.util.ResponseResult;import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiOperation;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.PostMapping;import org.springframework.web.bind.annotation.RestController;import java.util.List;@RestController@Api(tags = "用户管理相关接口")public class UserController {    @Autowired    private UserRepository userRepository;    //查询所有    @GetMapping("/users")    @ApiOperation("查询所有用户的接口")    public ResponseResult> selectUsers()    {         List usersList= userRepository.findAll();         return Response.createOkResp(usersList);    }    //根据id查询    @GetMapping("/users/{id}")    @ApiOperation("根据id查询用户的接口")    @ApiImplicitParam(name = "id", value = "用户id", required = true)    public ResponseResult selectUserById(@PathVariable(name = "id") int id)    {         User user= userRepository.findById(id).get();         return Response.createOkResp(user);    }    //添加    @PostMapping("/users")    @ApiOperation("添加用户")    public ResponseResult addUser(User user)    {        userRepository.save(user);        return Response.createOkResp("add success");    }}
这里边使用到了多个注解:@Api注解: 用来标记当前 Controller 的功能。@ApiOperation注解:用来标记一个方法的作用。@ApiImplicitParam注解:用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。如果有多个参数,则需要使用多个 @ApiImplicitParam 注解来描述,多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。需要注意的是,@ApiImplicitParam 注解中虽然可以指定参数是必填的,但是却不能代替 @RequestParam(required = true) ,前者的必填只是在 Swagger2 框架内必填,抛弃了 Swagger2 ,这个限制就没用了,所以假如开发者需要指定一个参数必填, @RequestParam(required = true) 注解还是不能省略。

3.6 参数是对象时

如果参数是一个对象(例如上文的添加接口),对于参数的描述也可以放在实体类中。

package com.example.swagger.pojo;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;import lombok.AllArgsConstructor;import lombok.Data;import lombok.NoArgsConstructor;import javax.persistence.*;@Data@NoArgsConstructor@AllArgsConstructor@Entity@Table(name = "users")@ApiModel(description = "用户字段")public class User {    @Id    @GeneratedValue(strategy = GenerationType.IDENTITY)    @ApiModelProperty(value = "用户id", name = "id",  example = "1")    private int id;    @ApiModelProperty(value = "用户名", name = "uname", required = true, example = "daimenglaoshi")    private String uname;    @ApiModelProperty(value = "年龄", name = "age",  example = "18")    private int age;}

3.7 查看接口文档

http://localhost:8080/swagger-ui.html

·

关键词: 我们就来看 有一个好 根据需要