Swagger笔记

最新推荐文章于 2021-09-18 10:04:40 发布

HELLFS

最新推荐文章于 2021-09-18 10:04:40 发布

阅读量111

点赞数

分类专栏： Swagger2 文章标签： swagger2

本文链接：https://blog.csdn.net/zhangruilinmoo/article/details/113885634

版权

Swagger2 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

文章目录

Swagger

Swagger

Springboot继承Swagger

1.新建一个Springboot-web项目

2.添加swagger依赖

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

3.编写Hello World工程

package cn.com.rikylinz.controller;

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

@RestController
public class TestController {

    @GetMapping("/hello")
    //@RequestMapping(value = "/hello",method = RequestMethod.GET)//效果跟上面一个注解一样
    public String hello(){
        return "Hello World!";
    }
}

4.配置Swagger

通常通过一个config文件进行配置Swagger

package cn.com.rikylinz.config;

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    /**
     * 配置Swagger信息
     * @return  ApiInfo
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Moo",
                "https://blog.csdn.net/zhangruilinmoo", "www.koooooooo@126.com");

        return new ApiInfo(
                "Moo测试主题",
                "Moo描述",
                "1.0",
                "https://blog.csdn.net/zhangruilinmoo", contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

5.测试即可

Swagger配置扫描接口

Docket.select()//开启配置扫描接口
 .paths(PathSelectors.ant("指定访问路径"))//扫描路径条件
 .apis(RequestHandlerSelectors.basePackage("指定包路径"))//扫描指定包路径
 .build()//构建

PathSelectors类的方法：

Predicate any() ：扫描所有访问路径的接口
Predicate none()：不扫描所有访问路径的接口
Predicate regex(final String pathRegex)：扫描符合正则的访问路径的接口
Predicate ant(final String antPattern)：扫描指定访问路径的接口

RequestHandlerSelectors类的方法：

Predicate any() ：扫描所有包
Predicate none()：不扫描所有包（通俗：不扫描）
Predicate basePackage(final String basePackage)：指定要扫描的包
Predicate withMethodAnnotation(final Class<? extends Annotation> annotation)：扫描方法上指定注解的方法，进而注册Bean，放入容器中管理
Predicate withClassAnnotation(final Class<? extends Annotation> annotation)：扫描类上指定注解的类，进而注册Bean，放入容器中管理

配置是否启动Swagger

new Docket
 .enable(false)
 .build()//构建

enable是否启动Swagger，默认为true；如果为false，则swagger不能再浏览器中访问

开发、测试环境可以使用，但生产环境不可以使用swagger

new Docket.enable(flagEnable(environment))

/**
 * 设置某些环境可以使用swagger
 * @param environment   environment
 * @return boolean
 */
private boolean flagEnable(Environment environment){
    //设置Swagger显示的环境
    Profiles profiles = Profiles.of("dev", "test");
    //通过environment.acceptsProfiles方法监听环境，判断是否处于自己设置的环境中
    return environment.acceptsProfiles(profiles);
}

配置API文档的分组

new Docket.groupName("分组名")

如何配置多个分组？

多个Docket实例即可，形成了协同开发模式

@Bean
public Docket docketA(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("A开发人员");
}

@Bean
public Docket docketB(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("B开发人员");
}

@Bean
public Docket docketC(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("C开发人员");
}

Swagger配置类完成版

package cn.com.rikylinz.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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docketA(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A开发人员");
    }

    @Bean
    public Docket docketB(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B开发人员");
    }

    @Bean
    public Docket docketC(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C开发人员");
    }

    /**
     * 配置Swagger Bean实例
     * @return  Docket
     */
    @Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flagEnable(environment))
                .groupName("Moo")
                .select()
                //需要RequestHandler，但RequestHandler是接口，这里需要RequestHandlerSelectors
                //RequestHandlerSelectors:配置要扫描接口的方式
                .apis(RequestHandlerSelectors.basePackage("cn.com.zhangruilin.controller"))
                //扫描指定访问路径
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置Swagger信息
     * @return  ApiInfo
     */
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("Moo",
                "https://blog.csdn.net/zhangruilinmoo", "www.koooooooo@126.com");

        return new ApiInfo(
                "Moo测试主题",//标题
                "Moo描述",//描述
                "1.0",//版本
                "https://blog.csdn.net/zhangruilinmoo",//组织链接
                contact,//联系人信息
                "Apache 2.0",//许可
                "http://www.apache.org/licenses/LICENSE-2.0",//许可链接
                new ArrayList()//扩展
        );
    }

    /**
     * 设置某些环境可以使用swagger
     * @param environment   environment
     * @return boolean
     */
    private boolean flagEnable(Environment environment){
        //设置Swagger显示的环境
        Profiles profiles = Profiles.of("dev", "test");
        //通过environment.acceptsProfiles方法监听环境，判断是否处于自己设置的环境中
        return environment.acceptsProfiles(profiles);
    }
}

Swagger注解

@Api() ：用于类，表示标识这个类是swagger的资源

参数说明：

参数名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	例如, “application/json, application/xml”
consumes	例如, “application/json, application/xml”
protocols	取值：http, https, ws, wss
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏

@ApiOperation()：用于方法，表示一个http请求的操作，描述当前方法

参数说明：

参数名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	例如, “application/json, application/xml”
consumes	例如, “application/json, application/xml”
protocols	取值：http, https, ws, wss
authorizations	高级特性认证时配置
hidden	配置为true 将在文档中隐藏
response	返回的对象
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的状态码默认 200
extensions	扩展属性

@ApiParam()：用于方法，参数，字段说明

参数说明：

参数名称	备注
name	属性名称
value	属性值
defaultValue	默认属性值
allowableValues	可以不配置
required	是否属性必填
access	不过多描述
allowMultiple	默认为false
hidden	隐藏该属性
example	举例子

@ApiModel()：用于类，表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()：用于属性上，表示对model属性的说明或者数据操作更改
@ApiIgnore()：用于类，方法，方法参数，表示这个方法、类和方法参数被忽略
@ApiImplicitParam()：用于方法，表示单独的请求参数
- 参数说明：
  - name：参数名，对应方法中单独的参数名称
  - value：参数中文说明
  - required：是否必填
  - paramType：参数类型，取值为 path、query、body、header、form
  - dataType：参数数据类型
  - defaultValue：默认值
  - …
@ApiImplicitParams()：用于方法，包含多个 @ApiImplicitParam

@ApiResponse：用于方法上，说明接口响应的一些信息

参数说明：

参数名称	备注
code	http的状态码
message	描述
response	默认响应类 Void
reference	参考ApiOperation中配置
responseHeaders	参考 ResponseHeader 属性配置说明
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效

@ApiResponses：组装了多个 @ApiResponse
- 参数说明：
  - value ：多个ApiResponse配置
@ResponseHeader：响应头设置
- 参数说明：
  - 参数名称备注
    name 响应头名称
    description 头描述
    response 默认响应类 Void
    responseContainer 这些对象是有效的 “List”, “Set” or “Map”.，其他无效

参数名称	备注
name	响应头名称
description	头描述
response	默认响应类 Void
responseContainer	这些对象是有效的 “List”, “Set” or “Map”.，其他无效

小知识

如何让实体类扫描到swagger中

//只要我们接口中返回值中存在实体类，就会被扫描到Swagger中
    @ApiOperation(value = "测试User")
    @PostMapping("/user")
    public User user(){
        return new User();
    }

HELLFS

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Swagger笔记

文章目录SwaggerSpringboot继承SwaggerSwagger配置扫描接口配置是否启动Swagger配置API文档的分组Swagger配置类完成版Swagger注解小知识SwaggerSpringboot继承Swagger1.新建一个Springboot-web项目2.添加swagger依赖<dependency> <groupId>io.springfox</groupId> <a
复制链接

扫一扫