spring boot 配置 swagger

Maven

增加 Swagger2 所需依赖,pom.xml 配置如下:

<!-- Swagger2 Begin -->
<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>
<!-- Swagger2 End -->

配置 Swagger2

注意:RequestHandlerSelectors.basePackage("com.xxxx.myshop.service") 为 Controller 包路径,不然生成的文档扫描不到接口

创建一个名为 Swagger2Configuration 的 Java 配置类,代码如下:

package com.funtl.myshop.commons.service.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger2Configuration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xxxx.myshop.service"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("MyShop API 文档")
                .description("MyShop API 网关接口,http://www.xxxx.com")
                .termsOfServiceUrl("http://www.xxxx.com")
                .version("1.0.0")
                .build();
    }
}

启用 Swagger2

Application 中加上注解 @EnableSwagger2 表示开启 Swagger

package com.funtl.myshop.service.reg;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.stream.annotation.EnableBinding;
import org.springframework.cloud.stream.messaging.Source;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableAsync;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;

@SpringBootApplication
@EnableSwagger2
public class MyShopServiceRegApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyShopServiceRegApplication.class, args);
    }
}

使用 Swagger2

在 Controller 中增加 Swagger2 相关注解,代码如下:

  paramType=“header”, header中传入token进行接口验证

  paramType=“query”, 正常传参

package com.xh.loanafter.rest.modular.auth.controller;

import com.xh.loanafter.core.exception.GunsException;
import com.xh.loanafter.rest.common.exception.BizExceptionEnum;
import com.xh.loanafter.rest.modular.auth.controller.dto.AuthRequest;
import com.xh.loanafter.rest.modular.auth.controller.dto.AuthResponse;
import com.xh.loanafter.rest.modular.auth.domain.po.TestUser;
import com.xh.loanafter.rest.modular.auth.util.JwtTokenUtil;
import com.xh.loanafter.rest.modular.auth.validator.IReqValidator;
import com.xh.loanafter.rest.modular.auth.validator.impl.DbValidator;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import javax.annotation.Resource;



    @ApiOperation(value = "测试接口", notes = "以实体类为参数,单个参数")
    @RequestMapping(value = "testApi", method = RequestMethod.POST)
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "header", dataType = "String", name = "Authorization", value = "token标记", required = true),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "account", value = "姓名", required = true),
            @ApiImplicitParam(paramType = "query", dataType = "String", name = "password", value = "密码", required = true)})
    public String testApi(String account,String password) {
        TestUser testUser = new TestUser();
        testUser.setAccount(account);
        testUser.setPassword(password);
        return testUser.toString();
    }


}

 

访问 Swagger2

访问地址:http://localhost:8080/swagger-ui.html

@Api:用在请求的类上,表示对类的说明
    tags="说明该类的作用,可以在UI界面上看到的注解"
    value="该参数没什么意义,在UI界面上也看到,所以不需要配置"
 
 
@ApiOperation:用在请求的方法上,说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"
 
 
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
    @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
        name:参数名
        value:参数的汉字说明、解释
        required:参数是否必须传
        paramType:参数放在哪个地方
            · header --> 请求参数的获取:@RequestHeader
            · query --> 请求参数的获取:@RequestParam
            · path(用于restful接口)--> 请求参数的获取:@PathVariable
            · body(不常用)
            · form(不常用)    
        dataType:参数类型,默认String,其它值dataType="Integer"       
        defaultValue:参数的默认值
 
 
@ApiResponses:用在请求的方法上,表示一组响应
    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
        code:数字,例如400
        message:信息,例如"请求参数没填好"
        response:抛出异常的类
 
 
@ApiModel:用于响应类上,表示一个返回响应数据的信息
            (这种一般用在post创建的时候,使用@RequestBody这样的场景,
            请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiModelProperty:用在属性上,描述响应类的属性

1、@Api:用在请求的类上,说明该类的作用
     tags="说明该类的作用"
     value="该参数没什么意义,所以不需要配置"
示例:

@Api(tags="APP用户注册Controller")

2、@ApiOperation:用在请求的方法上,说明方法的作用
@ApiOperation:"用在请求的方法上,说明方法的作用"
    value="说明方法的作用"
    notes="方法的备注说明"
示例:

@ApiOperation(value="用户注册",notes="手机号、密码都是必输项,年龄随边填,但必须是数字")

3、@ApiImplicitParams:用在请求的方法上,包含一组参数说明
     @ApiImplicitParams:用在请求的方法上,包含一组参数说明
     @ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息       
        name:参数名
        value:参数的汉字说明、解释
        required:参数是否必须传
        paramType:参数放在哪个地方
            · header --> 请求参数的获取:@RequestHeader
            · query --> 请求参数的获取:@RequestParam
            · path(用于restful接口)--> 请求参数的获取:@PathVariable
            · body(不常用)
            · form(不常用)    
        dataType:参数类型,默认String,其它值dataType="Integer"       
        defaultValue:参数的默认值

示列:

 
  1. @ApiImplicitParams({

  2.     @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),

  3.     @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),

  4.     @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")

  5. })

4、@ApiResponses:用于请求的方法上,表示一组响应
     @ApiResponses:用于请求的方法上,表示一组响应
     @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
        code:数字,例如400
        message:信息,例如"请求参数没填好"
        response:抛出异常的类
示例:

 
  1. @ApiOperation(value = "select1请求",notes = "多个参数,多种的查询参数类型")

  2. @ApiResponses({

  3.     @ApiResponse(code=400,message="请求参数没填好"),

  4.     @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")

  5. })


5、@ApiModel:用于响应类上,表示一个返回响应数据的信息
     @ApiModel:用于响应类上,表示一个返回响应数据的信息
            (这种一般用在post创建的时候,使用@RequestBody这样的场景,
            请求参数无法使用@ApiImplicitParam注解进行描述的时候)
     @ApiModelProperty:用在属性上,描述响应类的属性


示例:

 
  1. import io.swagger.annotations.ApiModel;

  2. import io.swagger.annotations.ApiModelProperty;

  3.  
  4. import java.io.Serializable;

  5.  
  6. @ApiModel(description= "返回响应数据")

  7. public class RestMessage implements Serializable{

  8.  
  9.     @ApiModelProperty(value = "是否成功")

  10.     private boolean success=true;

  11.     @ApiModelProperty(value = "返回对象")

  12.     private Object data;

  13.     @ApiModelProperty(value = "错误编号")

  14.     private Integer errCode;

  15.     @ApiModelProperty(value = "错误信息")

  16.     private String message;

  17.  
  18.     /* getter/setter */

}

参考文献:https://blog.csdn.net/jiangyu1013/article/details/83107255

https://www.jianshu.com/p/3c9986f81ff0

  • 0
    点赞
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值