首页 > 其他分享 >SpringBoot整合Swagger生成接口文档

SpringBoot整合Swagger生成接口文档

时间：2022-11-30 15:38:10浏览次数：32  
标签：Swagger SpringBoot boot springframework 文档 org import springfox id


介绍:

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。 如果想深入分析项目源码，了解更多内容，见参考资料。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

使用

1.maven依赖

<dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-jdbc</artifactId>
        </dependency>

        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>

        <dependency>
            <groupId>tk.mybatis</groupId>
            <artifactId>mapper-spring-boot-starter</artifactId>
            <version>2.1.4</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

    </dependencies>

2.application.yml

spring:
  datasource:
    username: root
    password: root
    url: jdbc:mysql://127.0.0.1:3306/test?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    driver-class-name: com.mysql.cj.jdbc.Driver

    initialSize: 5
    minIdle: 5
    maxActive: 20
    maxWait: 60000
    timeBetweenEvictionRunsMillis: 60000
    minEvictableIdleTimeMillis: 300000
    validationQuery: SELECT 1 FROM DUAL
    testWhileIdle: true
    testOnBorrow: false
    testOnReturn: false
    poolPreparedStatements: true

3.swagger配置类

package com.hw.springbootswagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.ArrayList;
import java.util.List;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @program: springboot-swagger
 * @description:
 * @author: hw
 * @create: 2019-02-18 13:33
 **/
@Configuration
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hw.springbootswagger.controller"))//扫描包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")//标题提示
                .description("https://blog.csdn.net/qq_41594146")
                .termsOfServiceUrl("https://blog.csdn.net/qq_41594146")
                .version("1.0")
                .build();
    }
}

4.主启动类

package com.hw.springbootswagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;

@MapperScan("com.hw.springbootswagger.mapper")//tkmapper
@SpringBootApplication
@EnableSwagger2//swagger
public class SpringbootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

5.项目结构

SpringBoot整合Swagger生成接口文档_spring

6.controller层

package com.hw.springbootswagger.controller;

import com.hw.springbootswagger.entity.Person;
import com.hw.springbootswagger.mapper.PersonMapper;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.DeleteMapping;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;

/**
 * @program: springboot-swagger
 * @description:
 * @author: hw
 * @create: 2019-02-18 13:25
 **/
@RestController
@RequestMapping("test")
@Api(value = "测试接口Controller")//类注解
public class PersonController {

    @Autowired
    PersonMapper personMapper;

    @ApiOperation(value = "通过学生id查找学生", notes = "测试用接口")//方法说明
    @ApiImplicitParam(name = "id", value = "用户id", dataType = "Integer", required = true, paramType = "path")//参数说明
    @GetMapping("/get/{id}")
    public Person get(@PathVariable("id") int id) {
        Person person = personMapper.selectByPrimaryKey(id);
        return person;
    }


    @ApiOperation(value = "查找全部学生")
    @GetMapping("/getAll")
    public List<Person> getAll(){
        List<Person> people = personMapper.selectAll();
        return people;
    }

    @ApiOperation(value = "根据id删除学生")
    @ApiImplicitParam(name = "id",value = "用户id",dataType = "Integer",required = true)
    @DeleteMapping("delete/{id}")
    public int remove(@PathVariable int id){
        int i = personMapper.deleteByPrimaryKey(id);
        return i;
    }

    @ApiOperation(value = "添加学生")
    @ApiImplicitParam(name = "person",value = "学生对象",dataType = "Person",required = true)
    @PostMapping("/post")
    public int post(Person person){
        int insert = personMapper.insert(person);
        return insert;
    }


    @ApiOperation(value = "修改学生")
    @ApiImplicitParam(name = "person",value = "学生对象",dataType = "Person",required = true)
    @PostMapping("/put")
    public int put(Person person){
        int insert = personMapper.updateByPrimaryKeySelective(person);
        return insert;
    }
}

关于swagger的更多注解的使用:

SpringBoot整合Swagger生成接口文档_mysql_02

点击这个包下,然后看见下图的内容,点进去你想了解的注解,通过人家写的注释可以知晓注解和其参数的作用

SpringBoot整合Swagger生成接口文档_mysql_03

  • @Api：修饰整个类，描述Controller的作用
  • @ApiOperation：描述一个类的一个方法，或者说一个接口
  • @ApiParam：单个参数描述
  • @ApiModel：用对象来接收参数
  • @ApiProperty：用对象接收参数时，描述对象的一个字段
  • @ApiResponse：HTTP响应其中1个描述
  • @ApiResponses：HTTP响应整体描述
  • @ApiIgnore：使用该注解忽略这个API
  • @ApiError ：发生错误返回的信息
  • @ApiImplicitParam：一个请求参数
  • @ApiImplicitParams：多个请求参数

7.示例

标签：Swagger,SpringBoot,boot,springframework,文档,org,import,springfox,id
From： https://blog.51cto.com/u_15897407/5899814

相关文章

  • React学习笔记,文档中的大部分代码都有注释
    React主要用于构建UI。你可以在React里传递多种类型的参数，如声明代码，帮助你渲染出UI、也可以是静态的HTMLDOM元素、也可以传递动态变量、甚至是可交互的应用组件。1.使用(......
  • springboot项目同时支持http和https访问
    首先使用https需要一个server.keystore，生成教程可以然后开始改动项目：配置文件中填入server.keystore的信息server.ssl.key-store=server.keystoreserver.ssl.key-alias=tomc......
  • Java生成帮助文档
    在要生成帮助文档的目录下打开cmd   输入javadoc-encodingUTF-8-charrsetUTF-8要生成的Java文件  在生成的文件中打开index.html......
  • SpringBoot Maven RepackageMojo 打包失败原因
    maven打包提示：org/springframework/boot/maven/RepackageMojohasbeencompiledbyamorerecentversionoftheJavaRuntime(classfileversion61.0),thisver......
  • SpringMVC 项目中 创建SpringBoot，使用Hibernate和JPA
    起因：老项目是SpringMVC，为了之后能使用更方便的SpringBoot。所以在其中添加了SpringBoot项目，但是老项目SpringMVC使用的Hibernate，SpringBoot希望使用JPA 解决方案：......
  • 浏览器和服务器之间的通信 ajax axios 接口 接口文档
    浏览器和服务器通讯过程以咱们用的最多的浏览器为例,和服务器通讯的过程就像聊微信?浏览器:输入URL地址-->请求服务器:接收请求并返回对应的资源-->响应浏览器:......
  • SpringBoot
    《静态资源导入》根据源码：静态资源放在下面的目录都可以：   ......
  • SpringBoot2 配置
    一.Properties与YamlSpringBoot支持properties与yaml两种配置文件application.properties/application.ymlyaml简单使用1.yaml简介yaml是以数据为中心的，比json，xml更适合做配......
  • 如何写出一个好的设计文档?
    1.概要大部分的工程师都不重视设计文档的书写，对于一个需求，都是经过一些简单的讨论，写一个简单的方案甚至就是自己简单的想想就开始进行编码的工作。往往这种开发方式会导致开......
  • Swagger UI 显示元素注释内部
    1，在以下代码添加到 .csproj 文件中；<PropertyGroup><GenerateDocumentationFile>true</GenerateDocumentationFile></PropertyGroup>2，在Program.cs文件的。buil......

赞助商

阅读排行

网站主页关于我们联系我们网站地图

本网站内容转载自其他媒体，侵权联系[admin##ips99.com]。

Copyright © 2020-2023 IPS99 版权所有 IPS99