Swagger 01 入门

最新推荐文章于 2024-05-12 11:24:08 发布

进击的BUG

最新推荐文章于 2024-05-12 11:24:08 发布

阅读量585

点赞数 1

分类专栏： Swagger 文章标签： java swagger2

本文链接：https://blog.csdn.net/u012348305/article/details/115733429

版权

Swagger 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

Swagger

一、Swagger工作原理

在项目启动的过程中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，跟据这些Controller类中的方法生成相应的api文档。

二、swagger常用注解简述

1、@Api

描述：注解用于标注一个Controller（Class），加入@Api即标识能被scan

属性值：

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

参考：

@RestController( value= "swaggerController")
@RequestMapping(name="swaggerController", path = "/swagger")
@Api(value = "SwaggerTest",produces = "application/json, application/xml",
        consumes = "application/json, application/xml",protocols = "http",hidden = false)
public class SwaggerController {

2、@ApiOperation

描述：@ApiOperation 注解在用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

属性值：

属性	描述
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径可以不配置
position	如果配置多个Api 想改变显示的顺序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: 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	扩展属性

参考：

@GetMapping(name="sayHi",value = "/sayHi")
@ApiOperation(value="sayHi",httpMethod = "GET",code=200
        ,response = java.lang.String.class
        ,protocols = "http")
public String sayHi(){
    return "Hello Swagger";
}

3、@ApiParam

描述：@ApiParam作用于请求方法上，定义api参数的注解。

属性值：

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

参考：

@ApiOperation(value = "getUserName",httpMethod = "POST",code = 200)
public String getUserName(@ApiParam(name = "username",value = "用户名" , required = true , example = "tab") @RequestParam  String username){
    return username;
}

4、@ApiImplicitParams、@ApiImplicitParam

描述：@ApiImplicitParams用在请求方法上对一组参数的说明，@ApiImplicitParam用在请求方法上对单个参数的说明

属性值： @ApiImplicitParams的属性值只有 @ApiImplicitParam数组

属性	描述
name	参数名
value	参数的说明、描述
required	参数是否必须必填
paramType	参数放在哪个地方 query --> 请求参数的获取：@RequestParam header --> 请求参数的获取：@RequestHeader path（用于restful接口）–> 请求参数的获取：@PathVariable body（请求体）–> @RequestBody User user form（普通表单提交）
dataType	参数类型，默认String，其它值dataType=“Integer”
defaultValue	参数的默认值

参考：

@GetMapping(name ="getUserPassword" , value="/getUserPassword")
@ApiOperation(value = "getUserPassword",httpMethod = "GET")
@ApiImplicitParams({@ApiImplicitParam( name="password", value = "密码" , required = true , dataType = "Integer" , allowableValues = "1,2,3")})
public String getUserPassword( @RequestParam  String password){
    return "this is a "+password;
}

5、@ApiResponses、@ApiResponse

描述：@ApiResponses、@ApiResponse进行方法返回对象的说明。

属性值：

属性	描述
code	数字，例如400
message	信息，例如"请求参数没填好"
response	自定义的schema的实体类

参考：总体感觉没啥用

@GetMapping(name ="setResponseInfo" , value="/setResponseInfo")
@ApiOperation(value = "setResponseInfo",httpMethod = "GET")
@ApiImplicitParams({@ApiImplicitParam( name="name", value = "名称" , required = true )})
@ApiResponses({@ApiResponse(code = 200,message = "请求成功"),@ApiResponse(code = 400,message = "请求参数异常")})
public String setResponseInfo( @RequestParam  String name){
    return "Hi "+name;
}

6、@ApiModel、@ApiModelProperty

描述：@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候 @ApiModelProperty用来描述一个Model的属性。

属性值：

ApiModel

属性	描述
value	提供一个供选择的名称，默认为类名
description	对类的描述
parent	为模型提供一个超类以允许描述继承
discriminator	支持继承和多态，作为一个字段标识浮，以便于子类继承使用
subTypes	从这个模型继承的子类型的数组
reference	指定对相应类型定义的引用，覆盖指定的任何其他元数据

ApiModelProperty

属性	描述
value	A brief description of this property.
name	Allows overriding the name of the property
allowablevalues	限制参数可接受的值
access	Allows for filtering a property from the API documentation. See io.swagger.core.filter.SwaggerSpecFilter.
notes	标签描述，1.5已经没实际作用
datatype	指定数据类型可以是一个类或者原始类型
request	true/false 是否必填
position	属性位置排序默认0
hidden	是否展现 true/false 默认false
example	属性值的参考数据
readOnly	是否只读 ture/false
accessMode	允许指定模型的访问模式枚举为本类(AccessMode.READ_ONLY, READ_WRITE)
reference	指定对相应类型定义的引用，覆盖指定的任何其他元数据
allowEmptyValue	是否允许空值输入默认false
extensions	扩展属性

实例：

@ApiModel(value = "user",description = "用户相关入参")
public class UserParam {

@ApiModelProperty(name="userName" , value = "用户名称",dataType ="java.lang.String",position = 1,example = "tab")
    private String userName;

@ApiModelProperty(name="password" , value = "用户密码",dataType ="java.lang.String",position = 2,example =  "123",required = true,allowableValues = "1,2,3")
    private String password;

7、 @PathVariable

描述：@PathVariable用于获取get请求url路径上的参数，即参数绑定的作用，通俗的说是url中"?"前面绑定的参数。

属性值：

属性	描述
value	属性Key
name	同上
required	是否必填，默认必须

参考：使用率比较高但是功能表单一

@GetMapping(value = "/{user}")
public void test(@PathVariable("user") String user){
    System.out.println( "Hello "+ user);
}

8、 @RequestParam

描述：@RequestParam用于获取前端传过来的参数，可以是get、post请求，通俗的说是url中"?"后面拼接的每个参数。

属性值：

属性	描述
value	属性Key
name	同上
required	是否必填，默认必须
defaultValue	默认值

参考：上述demo

三、Swagger引入

springfox-swagger-ui依赖并不是必须的，可以使用第三方的UI，也可以自己写一套前端的UI集成进来。

我们就可以使用一个基于bootstrap写的UI。

1、引入依赖

1) 默认swagger

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

2) bootstrap

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

1)默认的swagger界面： http://localhost:8080/swagger-ui

在这里插入图片描述

引入第三方Bootstrap编写的UI：http://localhost:8080/doc.html#/home

在这里插入图片描述

2、基本配置

参考代码以当bootstrap为例

package com.fewin.config;

import com.google.common.base.Predicates;
import org.springframework.beans.factory.annotation.Value;
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.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.regex.Pattern;

/**
 * @Author : xuwl
 * @Date : Created on 上午10:04 2021/3/11
 * @Package Name : com.fewin.com.fewin.config
 * @Des : Swagger配置
 * @Version: v0.1
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean enable;

    private ApiInfo setApiInfo(String title, String version, String desc, Contact contact) {
        return new ApiInfoBuilder()
                .title(title)
                .description(desc)
                .contact(contact)
                .version(version)
                .build();
    }

    @Bean
    public Docket setSWaggerDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(setApiInfo("01sbd", "V0.1", "简单的swagger配置", new Contact("xuwl", "www.baidu.com", "tab_xu@123.com")))
                .enable(enable)
                .select()
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤所有的错误标签接口
                .paths(PathSelectors.ant("/swagger/**"))
                .build()
                .groupName("Swagger Paths");
    }

    @Bean
    public Docket setBaseDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(setApiInfo("01sbd", "V0.1", "简单的swagger配置", new Contact("xuwl", "www.baidu.com", "tab_xu@123.com")))
                .enable(enable)
                .select()
                .paths(PathSelectors.ant("/common/**"))
                .build()
                .groupName("Common Paths");
    }

    @Bean
    public Docket setSpecialDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(setApiInfo("01sbd", "V0.1", "简单的swagger配置", new Contact("xuwl", "www.baidu.com", "tab_xu@123.com")))
                .enable(enable)
                .select()
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//过滤所有的错误标签接口
                .paths(PathSelectors.ant("/test/**"))
                .build()
                .groupName("Special Paths");
                //.pathMapping("/test/"); //添加请求权限，进行所有请求的权限增加
    }
}

进击的BUG

关注

1
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
Swagger 01 入门

Swagger一、Swagger工作原理在项目启动的过程中，spring上下文在初始化的过程，框架自动跟据配置加载一些swagger相关的bean到当前的上下文中，并自动扫描系统中可能需要生成api文档那些类，并生成相应的信息缓存起来。如果项目MVC控制层用的是springMvc那么会自动扫描所有Controller类，跟据这些Controller类中的方法生成相应的api文档。二、swagger常用注解简述1、@Api描述：注解用于标注一个Controller（Class），加入@Api即标识
复制链接

扫一扫