AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

Swagger学习

2022-11-22 115
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： Swagger学习

Swagger简介


Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。

官网：https://swagger.io/

前后端分离会产生一个问题：全后端集成联调，前端人员和后端人员无法做到“即使协商，尽早解决”，最终导致问题集中爆发


解决方案：


  1. 前后端测试接口：postman
  2. 后端提供接口，需要实时更新最新的消息及改动。


Swagger


  • 号称世界上1最流行的Api框架
  • RestFul Api 文档在线自动生成工具（APi文档与APIdi定义同步更新）
  • 直接运行，可以在线测试API接口
  • 支持多种语言：（Java ， PHP）


Spring Boot集成Swagger


1，新建一个SpringBoot项目


2，导入相关依赖


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


3,编写一个Hello工程


@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}


4，配置Swagger


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


5，测试运行：http://localhost:8080/swagger-ui.html 显示如下页面


7d51347fa4c44bf38b43446b823b5c73.png


配置Swagger


Swagger的bean实例Docker


@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    public static final Contact DEFAULT_CONTACT = new Contact(
            "qijian",
            "https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
            "183@qq.com");
    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "Api Documentation  of qijian",
                "作者最帅",
                "1.0",
                "urn:https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>()
        );
    }
}


ec5b441221714f9b92b0c4386f08852b.png


Swagger配置扫描接口


@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    public static final Contact DEFAULT_CONTACT = new Contact(
            "qijian",
            "https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
            "183@qq.com");
    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
              .enable(true)//是否起用swagger ， 当为false时swagger是不能使用的
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackge:指定扫描的包
                //any()：扫描全部
                //none() : 不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotion:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qijian.swagger.controller"))
                //paths() 过滤路径
//                .paths(PathSelectors.ant("com1.qijian.demo"))
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "Api Documentation  of qijian",
                "作者最帅",
                "1.0",
                "urn:https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>()
        );
    }
}

e267c346bb354793b9e03ded1e634f49.png


当只希望在生产环境中使用，在发布的时候不使用swagger，怎么做？

1，判断是不是生产环境 flag = false

2，注入enable（flag）


    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev" , "test");
        //通过environment.acceptsProfiles判断是否在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//是否起用swagger ， 默认为true ， 当为false时swagger是不能使用的
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackge:指定扫描的包
                //any()：扫描全部
                //none() : 不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotion:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qijian.swagger.controller"))
                //paths() 过滤路径
//                .paths(PathSelectors.ant("com1.qijian.demo"))
                .build();
    }


配置API的分组


.groupName("A");
• 1


如何配置多个分组，实现多个Docket实例即可


@Bean
public Docket docket1(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("A");
}
@Bean
public Docket docket2(){
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("C");
}


项目代码：


目录结构


b77d87fa1e654bb6b9ab3cb3abe3fc23.png


pom.xml


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


SwaggerConfig （swagger配置类）


package com.qijian.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;
/**
 * @author qijian
 * @version 1.0
 * @description
 * @updateRemark
 * @updateUser
 * @createDate 2021/11/4 20:52
 * @updateDate 2021/11/4 20:52
 **/
@Configuration
@EnableSwagger2//开启Swagger2
public class SwaggerConfig {
    public static final Contact DEFAULT_CONTACT = new Contact(
            "qijian",
            "https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
            "183@qq.com");
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("A");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("C");
    }
    //配置Swagger的Docket的Bean实例
    @Bean
    public Docket docket(Environment environment){
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev" , "test");
        //通过environment.acceptsProfiles判断是否在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)//是否起用swagger ， 默认为true ， 当为false时swagger是不能使用的
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackge:指定扫描的包
                //any()：扫描全部
                //none() : 不扫描
                //withClassAnnotation：扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotion:扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.qijian.swagger.controller"))
                //paths() 过滤路径
//                .paths(PathSelectors.ant("com1.qijian.demo"))
                .build();
    }
    private ApiInfo apiInfo(){
        return new ApiInfo(
                "Api Documentation  of qijian",
                "作者最帅",
                "1.0",
                "urn:https://blog.csdn.net/qq_43663493?spm=1000.2115.3001.5343",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>()
        );
    }
}


the code of hellocontroller.java


package com.qijian.swagger.controller;
import com.qijian.swagger.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
 * @author qijian
 * @version 1.0
 * @description
 * @updateRemark
 * @updateUser
 * @createDate 2021/11/4 20:47
 * @updateDate 2021/11/4 20:47
 **/
@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
    //只要我的接口中存在实体类，返回值中存在实体类，它就会扫描到Swagger中
    @PostMapping(value = "/user")
    public User user(){
        return new User();
    }
    @ApiOperation("Hello控制2")
    @GetMapping(value = "/hello2")
    public String hello(@ApiParam("用户名") String userName){
        return "hello" + userName;
    }
}


the code of user.java


package com.qijian.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
/**
 * @author qijian
 * @version 1.0
 * @description
 * @updateRemark
 * @updateUser
 * @createDate 2021/11/4 22:56
 * @updateDate 2021/11/4 22:56
 **/
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}


启动类：


package com.qijian.swagger;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class SwaggerDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }
}


application配置文件

c394344398464507998755cca88faee8.png


总结


1，我们可以通过Swagger 给一些比较难以理解的属性或者接口，添加注解信息

2,接口文档实时更新

3，可以在线测试


常用注解：


@Api()用于类； 表示标识这个类是swagger的资源 @Api(value="用户controller",tags={"用户操作接口"})

@ApiOperation()用于方法；表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类 表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段 ； 表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数 ； 表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法 ； 表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam



文档实时更新


3，可以在线测试


常用注解：


@Api()用于类； 表示标识这个类是swagger的资源 @Api(value="用户controller",tags={"用户操作接口"})

@ApiOperation()用于方法；表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明； 表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类 表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段 ； 表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数 ； 表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法 ； 表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

文章标签：
Java
PHP
前端开发
容器
测试技术
Docker
Spring
API
游客kqqcexmiur45e
目录
相关文章
java冯坚持
|
4月前
|
前端开发 Java 程序员
springboot 学习十五：Spring Boot 优雅的集成Swagger2、Knife4j
这篇文章是关于如何在Spring Boot项目中集成Swagger2和Knife4j来生成和美化API接口文档的详细教程。
java冯坚持
495 1
1483290837038108
|
7月前
|
存储 API Go
学习gin-vue-admin之创建api和swagger
学习gin-vue-admin之创建api和swagger
1483290837038108
103 0
w风雨无阻w
|
Java API 网络架构
Spring Boot 学习研究笔记(六) -使用 Swagger 集成文档
Spring Boot 学习研究笔记(六) -使用 Swagger 集成文档
w风雨无阻w
78 0
码上言
|
前端开发 数据可视化 Java
从零学习Swagger3.0
从零学习Swagger3.0
码上言
188 0
叫我默语
|
安全 API
集成Swagger 学习（二）
集成Swagger 学习（二）
叫我默语
112 0
叫我默语
|
前端开发 Java API
集成Swagger 学习（一）
集成Swagger 学习（一）
叫我默语
115 0
优惠码发放
|
XML JSON 开发框架
Asp.Net Core 3.1 学习4、Web Api 中基于JWT的token验证及Swagger使用
优惠码发放
2904 0
嗯哼9925
|
API 开发工具
ABP理论学习之Swagger UI集成
嗯哼9925
1707 0
杨俊明
|
程序员 Spring API
spring cloud 学习(10) - 利用springfox集成swagger
对绝大多数程序员而言，写接口文档是一件痛苦的事情，相对文档，他们更愿意写代码。最理想的情况就是：代码即文档！服务开发完成后，部署上去文档就自动生成，没错，这就是springfox + swagger要解决的问题！ swagger号称 THE WORLD'S MOST POPULAR API TOOLING。
杨俊明
1663 0
wljslmz
|
3月前
|
Java 测试技术 API
详解Swagger：Spring Boot中的API文档生成与测试工具
详解Swagger：Spring Boot中的API文档生成与测试工具
wljslmz
107 4

热门文章

最新文章

  • 1
    SpringBootWeb篇-入门了解Swagger的具体使用
  • 2
    Spring Cloud Gateway 聚合swagger文档
  • 3
    Swagger Editor与Swagger-UI神器使用
  • 4
    三：.net core（.NET 6）给swagger添加文档注释详细步骤
  • 5
    Spring Boot 集成Swagger
  • 6
    NestJS 7.x 折腾记: (4) Swagger接入及相关用法
  • 7
    接口文档生成神器-Swagger3
  • 8
    实战篇：解决swagger和自定义参数解析器的功能冲突
  • 9
    Springboot集成Swagger2
  • 10
    SpringBoot 整合 Swagger 2
  • 1
    SpringBootWeb篇-入门了解Swagger的具体使用
    32
  • 2
    详解Swagger：Spring Boot中的API文档生成与测试工具
    107
  • 3
    SpringSecurity结合knife4j实现swagger文档
    210
  • 4
    springboot 学习十五：Spring Boot 优雅的集成Swagger2、Knife4j
    495
  • 5
    mybatis使用三：springboot整合mybatis，使用PageHelper 进行分页操作，并整合swagger2。使用正规的开发模式：定义统一的数据返回格式和请求模块
    139
  • 6
    Springfox Swagger3从入门案例
    148
  • 7
    Springfox Swagger2从入门到精通
    171
  • 8
    Swagger接口文档 —— 手把手教学，全方位超详细小白能看懂，百分百能用Java版
    1310
  • 9
    开发指南040-swagger加header
    153
  • 10
    springboot 集成 swagger 2.x 和 3.0 以及 Failed to start bean ‘documentationPluginsBootstrapper‘问题的解决
    608

    • 相关电子书

    更多
  • Java Spring Boot开发实战系列课程【第15讲】：Spring Boot 2.0 API与Spring REST Docs实战
  • 低代码开发师（初级）实战教程
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    阿里云oss简介和如何对接使用