Swagger3快速入门

Swagger快速入门SpringBoot集成Swagger依赖配置类-SwaggerConfig访问号称世界上最流行的API框架Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新直接运行，在线测试API支持多种语言（如：Java，PHP等）官网：https://swagger.io/快速入门SpringBoot集成Swagger依赖<depend

向天再借500年

1370人浏览 · 2021-07-16 12:09:36

向天再借500年 · 2021-07-16 12:09:36 发布

号称世界上最流行的API框架

Restful Api 文档在线自动生成器 => API 文档与API 定义同步更新
直接运行，在线测试API
支持多种语言（如：Java，PHP等）
官网：https://swagger.io/

快速入门SpringBoot集成Swagger

依赖

swagger3依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

但是我实际使用的时候总是有各种报错，如果有请把版本降2.9.2

<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>

配置类-SwaggerConfig

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {
}

访问

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

在这里插入图片描述

配置Swagger

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger

//配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

可以通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {
   Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
   return new ApiInfo(
           "标题", // 标题
           "描述", // 描述
           "v1.0", // 版本
           "http://terms.service.url/组织链接", // 组织链接
           contact, // 联系人信息
           "Apach 2.0 许可", // 许可
           "许可链接", // 许可连接
           new ArrayList<>()// 扩展
  );
}

完整版

package com.blb.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

    private  ApiInfo apiInfo(){
        Contact contact=new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com");
        return new ApiInfo(
                "dyk的swagger文档",
                "我的 API文档",
                "v1.0",
                "https://blog.csdn.net/qq_44866153",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()


        );
    }
}

方法名	描述
select	获取Docket中的选择器,返回apiSelectorBuilder构造选择器
apis(RequestHandlerSelectors.basePackage(“com.blb.controller”))	设定扫描那个包（包含子包）

package com.blb.config;

import org.springframework.boot.autoconfigure.info.ProjectInfoProperties;
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.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()//获取Docket中的选择器,返回apiSelectorBuilder构造选择器 如扫描什么包的注解
                .apis(RequestHandlerSelectors.basePackage("com.blb.controller"))//设定扫描那个包（包含子包）
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo2());
    }

    private  ApiInfo apiInfo(){
        Contact contact=new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com");
        return new ApiInfo(
                "dyk的swagger文档",
                "我的 API文档",
                "v1.0",
                "https://blog.csdn.net/qq_44866153",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()


        );
    }

    private ApiInfo apiInfo2(){

        return new ApiInfoBuilder()
                .title("dyk的swagger文档")
                .description("我的 API文档")
                .version("v1.0")
                .contact(new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

访问

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

在这里插入图片描述

controller

package com.blb.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TestController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

测试接口

在这里插入图片描述

正则表达式设置路径范围

controller没加@RequestMapping("/swagger")时

package com.blb.config;

import com.blb.annotation.MySwaggerAnnotation;


import com.google.common.base.Predicates;
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;

import java.util.ArrayList;


import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(Predicates.not(//not取反
                        withMethodAnnotation(MySwaggerAnnotation.class)))  //方法上有MySwaggerAnnotation注解时返回true
                .apis(RequestHandlerSelectors.basePackage("com.blb.controller"))
                .paths(PathSelectors.regex("/swagger/.*"))//使用正则表达式，约束生成api文档的路径
                .build().apiInfo(apiInfo2());
    }

    private  ApiInfo apiInfo(){
        Contact contact=new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com");
        return new ApiInfo(
                "dyk的swagger文档",
                "我的 API文档",
                "v1.0",
                "https://blog.csdn.net/qq_44866153",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()


        );
    }

    private ApiInfo apiInfo2(){

        return new ApiInfoBuilder()
                .title("dyk的swagger文档")
                .description("我的 API文档")
                .version("v1.0")
                .contact(new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

在这里插入图片描述
加了@RequestMapping("/swagger")后

多个规则

package com.blb.config;

import com.blb.annotation.MySwaggerAnnotation;


import com.google.common.base.Predicates;
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;

import java.util.ArrayList;


import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(Predicates.not(//not取反
                        withMethodAnnotation(MySwaggerAnnotation.class)))  //方法上有MySwaggerAnnotation注解时返回true
                .apis(RequestHandlerSelectors.basePackage("com.blb.controller"))
                .paths(
                        Predicates.or(//多个规则符合任意一个即可通过
                                PathSelectors.regex("/swagger/.*"),
                                PathSelectors.regex("/swagger2/.*"),
                                PathSelectors.regex("/.*")
                        )

                        )//使用正则表达式，约束生成api文档的路径

                .build().apiInfo(apiInfo2());
    }

    private  ApiInfo apiInfo(){
        Contact contact=new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com");
        return new ApiInfo(
                "dyk的swagger文档",
                "我的 API文档",
                "v1.0",
                "https://blog.csdn.net/qq_44866153",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()


        );
    }

    private ApiInfo apiInfo2(){

        return new ApiInfoBuilder()
                .title("dyk的swagger文档")
                .description("我的 API文档")
                .version("v1.0")
                .contact(new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

swagger的注解

@Api

作用：用来指定接口的描述文字
修饰范围：作用在类上
参数
value：是详细描述
tags：是标题

@RestController
@Api(tags = "测试服务的接口描述")
public class TestController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

在这里插入图片描述

@ApiOperation()

作用：用来对接口中具体的方法做描述
修饰范围：作用在方法上

@RequestMapping("/findAll")
    @ApiOperation(value = "查询所有用户接口",

    notes = "<span style='color:red;'>描述:</span>&nbsp;用来查询所有用户信息的接口")
    public Map<String,Object> findAll(){
        Map<String,Object> map=new HashMap<>();
        map.put("success","查询成功");
        map.put("state",true);
        return map;
    }

在这里插入图片描述

value：用来对接口的说明
notes：用来对接口的详细描述

@ApiImplicitParams

作用：用来接口中的参数进行说明
修饰范围：作用在方法上

@PostMapping("/save")
    @ApiOperation(value = "保存用户信息接口",notes = "<span style='color:red;'>描述：</span>&nbsp;用来保存用户信息的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",dataType = "String",defaultValue ="1"),
            @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",defaultValue ="dyk")
    })
    public Map<String,Object> save(String id,String name){
        Map<String,Object> map=new HashMap<>();
        map.put("success","查询成功");
        map.put("state",true);
        return map;
    }

在这里插入图片描述
可以看到它还是以？后面拼接参数的方式传递的参数，

rest风格

@PostMapping("/save/{id}/{name}")
    @ApiOperation(value = "保存用户信息接口",notes = "<span style='color:red;'>描述：</span>&nbsp;用来保存用户信息的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",dataType = "String",defaultValue ="1",paramType = "path"),
            @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",defaultValue ="dyk",paramType = "path")
    })
    public Map<String,Object> save(@PathVariable("id") String id, @PathVariable("name") String name){
        Map<String,Object> map=new HashMap<>();
        map.put("success","查询成功");
        map.put("state",true);
        return map;
    }

在这里插入图片描述

@ApiResponses

作用：用于请求方法上，表示一组响应
修饰范围：作用在方法上

@ApiResponses({
            @ApiResponse(code=400,message = "参数有问题"),
            @ApiResponse(code = 404,message = "请求页面路径或跳转路径不正确"),
            @ApiResponse(code = 200,message = "添加用户成功")
    })
    public Map<String,Object> save(@PathVariable("id") String id, @PathVariable("name") String name){
        Map<String,Object> map=new HashMap<>();
        map.put("success","查询成功");
        map.put("state",true);
        return map;
    }

在这里插入图片描述

@ApiIgnore

忽略，当前注解描述的方法或者类型不生成api帮助文档

@ApiModel

描述一个实体类型,这个实体类型如果成为任何一个生成api帮助文档的方法
返回值类型的时候，次注解被解析

package com.blb.entity;

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

import java.io.Serializable;

@ApiModel(value = "User",description = "User实体类")
@Data
@NoArgsConstructor
@AllArgsConstructor
public class User implements Serializable {
    @ApiModelProperty(value = "主键",name = "主键id",required = false,example = "1",hidden = false)
        private  String id;
    @ApiModelProperty(value = "姓名",name = "姓名name",required = true,example = "dyk",hidden = false)
        private  String name;
    @ApiModelProperty(value = "密码",name = "密码password",required = true,example = "123",hidden = false)
        private String password;
}

controller

@RequestMapping("/getUser")
    public User User(){
        return  new User();
    }

在这里插入图片描述

自定义注解

让controller里的方法不显示在swaggerui里面

由于3.0的import com.google.common.base.Predicates;这个包一直导不进去我又换成2.9.2

swagger2访问

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

注解定义

package com.blb.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * @target() 描述当前的注解可以定义在什么资源上
 * 属性value
 *   定义具体的资源 包括：
 *  ElementType.METHOD 可以定义在方法上
 *  ElementType.TYPE  可以定义在类上
 *  ElementType.FIELD  可以定义在属性上
 *  ElementType.PARAMETER 可以定义在方法参数上
 *
 *
 * @Retention  当前注解在什么时候有效
 * 属性value
 * -  定义具体的生效标记
 *   RetentionPolicy.RUNTIME  运行时有效
 *   RetentionPolicy.SOURCE    源码中有效
 *   RetentionPolicy.CLASS     字节码有效
 */
@Target(value = {ElementType.TYPE,ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME )
public @interface MySwaggerAnnotation {

    //自定义注解中的属性，相当于@MySwaggerAnnotation(value="")

    String value() default "";
}

配置

package com.blb.config;

import com.blb.annotation.MySwaggerAnnotation;


import com.google.common.base.Predicates;
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;

import java.util.ArrayList;


import static springfox.documentation.builders.RequestHandlerSelectors.withMethodAnnotation;

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {

    //配置了Swagger的Docket的bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(Predicates.not(//not取反
                        withMethodAnnotation(MySwaggerAnnotation.class)))  //方法上有MySwaggerAnnotation注解时返回true
                .apis(RequestHandlerSelectors.basePackage("com.blb.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo2());
    }

    private  ApiInfo apiInfo(){
        Contact contact=new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com");
        return new ApiInfo(
                "dyk的swagger文档",
                "我的 API文档",
                "v1.0",
                "https://blog.csdn.net/qq_44866153",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>()


        );
    }

    private ApiInfo apiInfo2(){

        return new ApiInfoBuilder()
                .title("dyk的swagger文档")
                .description("我的 API文档")
                .version("v1.0")
                .contact(new Contact("dyk","https://blog.csdn.net/qq_44866153","1106649325@qq.com"))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

controller加上自定义注解

package com.blb.controller;

import com.blb.annotation.MySwaggerAnnotation;
import io.swagger.annotations.*;
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.HashMap;
import java.util.Map;

@RestController
@Api(tags = "用户服务的接口描述")
public class TestController {

   @MySwaggerAnnotation
    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }


    @RequestMapping("/findAll")
    @ApiOperation(value = "查询所有用户接口",

    notes = "<span style='color:red;'>描述:</span>&nbsp;用来查询所有用户信息的接口")
    public Map<String,Object> findAll(){
        Map<String,Object> map=new HashMap<>();
        map.put("success","查询成功");
        map.put("state",true);
        return map;
    }

    @PostMapping("/save/{id}/{name}")
    @ApiOperation(value = "保存用户信息接口",notes = "<span style='color:red;'>描述：</span>&nbsp;用来保存用户信息的接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",dataType = "String",defaultValue ="1",paramType = "path"),
            @ApiImplicitParam(name = "name",value = "用户姓名",dataType = "String",defaultValue ="dyk",paramType = "path")
    })

    @ApiResponses({
            @ApiResponse(code=400,message = "参数有问题"),
            @ApiResponse(code = 404,message = "请求页面路径或跳转路径不正确"),
            @ApiResponse(code = 200,message = "添加用户成功")
    })
    public Map<String,Object> save(@PathVariable("id") String id, @PathVariable("name") String name){
        Map<String,Object> map=new HashMap<>();
        map.put("success","查询成功");
        map.put("state",true);
        return map;
    }
}

在这里插入图片描述
可以看到默认忽略了hello 因为我在对应的controller方法上面加了自定义注解

美化swagger的插件

导入依赖

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>

访问

http://localhost:8080/doc.html

在这里插入图片描述
页面变得好看些了也变的方便些了

调式功能

在这里插入图片描述

注意

实际使用如果一输入ip地址发现报错java.lang.NumberFormatException: For input string: ""那就是@ApiModelProperty(value = “员工id”,example = “1”)要加入example属性，这也是实际使用时发现的问题，然后swagger3也是有一些报错暂时也没找到为什么，所有还是尽量使用swagger2，没有那么多错

CSDN学习社区

CSDN联合极客时间，共同打造面向开发者的精品内容学习社区，助力成长！

更多推荐

嵌入式作业（七）：基于Ardunio的STM32串口通信

嵌入式作业（七）0作业要求1Ardunio 完成STM32的串口通信（1）安装Ardunio IDE（2）stm32串口通信2关于 stduino IDE0作业要求安装 Ardunio IDE 和相关软件支持库，在Ardunio 完成STM32板子的串口通信程序：（1）持续向串口输出“Hello world！”；（2）当接收到“stop!”时，停止输出。网上有一个国人版的MCU集成开发平台， st

CSDN学习社区

JDBC详解

JDBC文章目录JDBC什么是JDBC?JDBC驱动程序:Java使用JDBC访问数据库的步骤:设置classpath:Oracle连接字符串的书写格式:简单的例子:常用数据库的驱动程序及JDBC URL:Oracle数据库:SQL Server数据库MySQL数据库Access数据库PreparedStatement接口:JNDI-数据源（Data Source）与连接池（Connection

CSDN学习社区

“模式识别与机器学习”学习笔记no2.再谈感知机

接**上篇：上篇主要进行了PLA，Pocket算法的理论过程分析和在给定数据集上利用pocket算法对数据集进行分类学习，得到错分数量最少的分类面。上篇中pocket算法的过程已经进行了编程和测试，框架已经建立了起来，这一篇主要上篇中没有提到或涉及不深的几个问题。1.数据集的构造。上篇是直接使用了题目给的向量，这次来根据正态分布来产生数据集。np.random.normal函数可以根据均值和方差生