欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

Spring Boot整合swagger2

程序员文章站 2022-07-02 20:59:51
...
  • 前言:

由于最近维护的项目增加了新的功能模块,本人维护的项目较为古老,jdk使用的都是1.6的;和最新的jdk14来说,差的不是一星半点;在后端接口开发完成后,往往还要再前端进行接口文档的书写,而且需求的变更导致后端接口的变化,还要再进行前端接口文档的维护,确实是相当的麻烦。由于以前接触过一点swagger的使用,隧建立了一个spring boot项目用来整合swagger,以提升自己的认识。

  • 新建spring boot项目,这里使用了Lombok插件以及spring-data-jpa,数据库使用的是MySQL8,目录结构如下

Spring Boot整合swagger2

  • 引入swagger2的jar包,在pom.xml中添加如下依赖,这里版本使用的是
<properties>
    <java.version>1.8</java.version>
    <swagger.version>2.9.2</swagger.version>
</properties>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>
<!-- swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>
  • 配置swagger
package com.yunxi.map.config;

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

/**
 * TODO swagger配置类
 *
 * @author xiaoshuaishuai
 * @date 2020-04-28 13:13
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("肖**", "157********", "******@163.com");
        return new ApiInfoBuilder()
                .title("一丛小溪地图项目接口")
                .description("个人项目")
                .contact(contact)
                .version("1.0.0")
                .build();
    }
}
  • 实体类配置(这里我的示例使用了这些类作为参数,个人觉得这样比较方便,也便于后期增加字段)
package com.yunxi.map.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.data.annotation.CreatedBy;
import org.springframework.data.annotation.CreatedDate;
import org.springframework.data.annotation.LastModifiedBy;
import org.springframework.data.annotation.LastModifiedDate;
import org.springframework.data.jpa.domain.support.AuditingEntityListener;

import javax.persistence.*;
import java.io.Serializable;
import java.util.Date;

/**
 * TODO 用户表
 *
 * @author xiaoshuaishuai
 * @date 2020-04-24 19:51
 */
@Data
@Entity
@ApiModel(value = "User对象", description = "用户表")
public class User implements Serializable {

    private static final long serialVersionUID = 41651381570588628L;

    @ApiModelProperty(value = "主键id", example = "1")
    @Id
    @Column(unique = true, nullable = false)
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ApiModelProperty(value = "用户名")
    @Column
    private String username;

    @ApiModelProperty(value = "密码")
    @Column
    private String password;

    @ApiModelProperty(value = "手机号码")
    @Column
    private String telephone;

    @ApiModelProperty(value = "邮箱地址")
    @Column
    private String eMail;

    @ApiModelProperty(value = "地址")
    @Column
    private String address;

    @ApiModelProperty(value = "用户头像url地址")
    @Column
    private String headSculptureUrl;

    @ApiModelProperty(value = "所属行政区划名称")
    @Column
    private String regionName;

    @ApiModelProperty(value = "所属行政区划代码")
    @Column
    private String regionCode;

    @ApiModelProperty(value = "创建时间")
    @Column
    private Date createTime;

    @ApiModelProperty(value = "创建人")
    @Column
    private String creator;

    @ApiModelProperty(value = "最近一次的修改时间")
    @Column
    private Date updateTime;

    @ApiModelProperty(value = "最近一次的修改人")
    @Column
    private String modifier;

    @ApiModelProperty(value = "备注")
    @Column
    private String remark;

}
package com.yunxi.map.dto;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.io.Serializable;

/**
 * TODO 用户数据传输类
 *
 * @author xiaoshuaishuai
 * @date 2020-04-30 9:52
 */
@Data
@ApiModel(value = "用户数据传输对象", description = "用户数据传输类")
public class UserDto implements Serializable {

    private static final long serialVersionUID = 7836123583196690829L;

    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;

    @ApiModelProperty(value = "邮箱", name = "eMail")
    private String eMail;

    @ApiModelProperty(value = "所属行政区划名称")
    private String regionName;

    @ApiModelProperty(value = "所属行政区划代码", hidden = true)
    private String regionCode;

}
  • 接口配置 
package com.yunxi.map.controller;

import com.yunxi.map.domain.User;
import com.yunxi.map.dto.UserDto;
import com.yunxi.map.service.UserService;
import com.yunxi.map.vo.UserVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;

/**
 * TODO 用户controller
 *
 * @author xiaoshuaishuai
 * @date 2020-04-30 9:48
 */
@Api(tags = {"用户接口"})
@RestController
@RequestMapping(value = "/user")
public class UserController {

    @Resource
    private UserService userService;

    @ApiOperation(value = "新增用户接口", notes = "参数采用表单提交")
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public void addUser(UserDto userDto) {
        try {
            userService.addUser(userDto);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @ApiOperation(value = "用户详情接口")
    @RequestMapping(value = "/get", method = RequestMethod.GET)
    public UserVo getUser() {
        return null;
    }

}

这里我的配置文件如下,我使用的是yml格式,properties文件可以改成自己对应的格式

server:
  port: 80
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/map?characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: root
  jpa:
    database: mysql
    database-platform: org.hibernate.dialect.MySQL8Dialect
    show-sql: true
    open-in-view: false # spring boot 默认开启视图,一般用不到,这里置为false
    hibernate:
      ddl-auto: update # 每次重启项目时,自动更新表结构

启动项目,在浏览器地址栏输入如下地址:http://localhost/swagger-ui.html

Spring Boot整合swagger2

Spring Boot整合swagger2

Spring Boot整合swagger2

上图就是我比较疑惑的地方了,如果有人知道如何解决,请留言指教;这里虽然名称不一样,但是最终传参是正确的,也就是说不影响你的使用

 

相关标签: spring Boot