还在使用 PostMan 测试接口？试试 Swagger 吧_swagger和postman的区别-CSDN博客

本文链接：https://blog.csdn.net/flycp/article/details/107720884

一，简介

什么是swagger？我们去官网看一下https://swagger.io/：简化Api开发，方便大规模Api设计。在这里插入图片描述

号称世界上最流行的Api框架。
RestFul Api文档在线生成工具。
直接运行，可以在线测试Api接口。
支持多种语言，java、php等。

二、如何使用Swagger

1.基本配置

使用swagger需要引入两个包，一个是核心包一个是前端展示的包。.

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

由于不是springBoot内置的starter所以我们需要，自定义配置文件，将swagger的实力Docket，交给springboot管理。

package com.swagger.controller.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;


/**
 * swagger配置信息
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * Swagger必须配置的Docket 实例
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //groupName 配置当前接口的分组
                .groupName("cp的接口")
                //配置是否启用swagger  false不启动
//                .enable(false)
                //配置需要扫描的接口包
                .select().apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                //需要过滤的包路径
//                .paths(PathSelectors.ant(""))
                .build();

    }
    /**
     * Swagger必须配置的Docket 实例
     * 可以配置多个实例，代表多个分组，
     */
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //groupName 配置当前接口的分组
                .groupName("小张的接口")
                //配置是否启用swagger  false不启动
//                .enable(false)
                //配置需要扫描的接口包
                .select().apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                //需要过滤的包路径
//                .paths(PathSelectors.ant(""))
                .build();

    }
    /**
     * swagger页面基本展示信息
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "c_pown Test Api",
                "c_pown Test Api", "1.0",
                "urn:tos",
                new Contact("cp", "www.baidu.com", "952793966@qq.com"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0");
    }

}

首先我们需要定义swagger页面基本展示信息，也就是ApiInfo，这里可以定义项目名称，公司名称，项目版本号等信息。可以在项目启动后访问http://localhost:8080/swagger-ui.html查看。
配置Swagger的Docket 实例，一个Docket可以说代表一个分组，可以是开发小组，也可以是个人。
通过Docket构造定义信息：
.groupName：配置当前接口的分组；
.enable:配置是否启用swagger false不启动;
.apis(RequestHandlerSelectors.basePackage(“com.swagger.controller”))：配置当前的接口所在包名。
.paths(PathSelectors.ant(""))：不需要生成接口文档的包路径。

这里我们配置了两个Docket实例可以看到页面是有两个分组：在这里插入图片描述

2.接口编写

package com.swagger.pojo;

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

@ApiModel("用户")
public class SysUser {
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;

    public SysUser() {
    }

    public SysUser(String username, String password) {
        this.username = username;
        this.password = password;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

package com.swagger.controller;

import com.swagger.pojo.SysUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@Api(tags = {"我的接口"} ,description = "我的接口Controller")
@RestController
public class Controller {
    /**
     * 定义接口最好使用GetMapping、PostMapping
     * 使用RequestMapping 会在页面生成多种接口
     * @return
     */
    @ApiOperation("欢迎页面接口")
    @GetMapping("/hello")
    public String helloword(@ApiParam("用户名")@RequestParam("username") String username){
        return "hello"+username;
    }

    /**
     * 如果使用
     */
    @ApiOperation("user接口")
    @PostMapping("/user")
    public SysUser user( SysUser sysUser){
        return new  SysUser("张三","李四");
    }

    /**
     * 最好不要使用RequestMapping
     * @param username
     * @return
     */
    @ApiOperation("最好不要使用")
    @RequestMapping("/RequestMapping")
    public String sss(@ApiParam("用户名")@RequestParam("username") String username){
        return "hello"+username;
    }
}

@ApiModel(“用户”) ：给实体类名添加swagger文档注释
@ApiModelProperty(“用户名”)：给实体类字段添加swagger文档注释
@Api(tags = {“我的接口”} ,description = “我的接口Controller”)：给接口类添加名称和注释
@ApiOperation(“欢迎页面接口”)：给接口添加名称
注意：这里最好不要使用@RequestMapping，因为RequestMapping既可以接收Get请求也可以接收Post请求，生成文档会生产多种请求。
使用@GetMapping 或者 @PostMapping指定请求类型。
我们看一下页面：
可以直接点击接口进行测试，方便又快捷：