SpringBoot 集成 Swageer2

添加Maven依赖

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.8.0</version>

        </dependency>

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>2.8.0</version>

        </dependency>

添加配置类

package com.erp.server.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.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2

@Configuration

public class SwaggerConfig {

    @Bean

    public Docket creatRestApi(){

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.erp.server.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    private ApiInfo apiInfo(){

        return new ApiInfoBuilder()

                .title("进销存系统")

                .description("这里是进销存系统的后台接口文档")

                //服务条款网址

                .termsOfServiceUrl("http://localhost:8080/swagger-ui.html")

                //联系人

                .contact(new Contact("wangbo","url地址", "email地址"))

                .version("1.0")

                .build();

    }

}

注解使用

@Api

用在请求类上，说明该类的作用。可以标记一个Controller类做为swagger文档资源。

value：url的路径值，在UI界面上也看到，可以不用配置。

String value() default "";

tags：说明该类的作用，可以在UI界面上看到的内容

String[] tags() default {""};

produces：配置返回数据类型，例如application/json，application/xml等

String produces() default "";

consumes：配置请求头，例如application/json，application/xml等

String protocols() default "";

authorizations：高级特性认证时配置

Authorization[] authorizations() default {@Authorization("")};

hidden：默认为false，配置为true将在文档中隐藏

boolean hidden() default false;

@ApiOperation

用在请求的方法上，说明方法的用途、作用

value：说明方法的用途、作用

String value();

notes：方法的备注说明

String notes() default "";

tags：

String[] tags() default {""};

response：返回的对象

Class<?> response() default Void.class;

responseContainer：这些对象是有效的List，Set，Map，其他是无效的

String responseContainer() default "";

responseReference：

String responseReference() default "";

httpMethod：可以配置其中HTTP请求方式

String httpMethod() default "";

nickname：

String nickname() default "";

produces：配置返回数据类型，例如application/json，application/xml等

String produces() default "";

consumes：配置请求头，例如application/json，application/xml等

String consumes() default "";

protocols：

String protocols() default "";

authorizations：高级特性认证时配置

Authorization[] authorizations() default {@Authorization("")};

hidden：默认为false，配置为true将在文档中隐藏

boolean hidden() default false;

responseHeaders：配置响应头

ResponseHeader[] responseHeaders() default {@ResponseHeader(

    name = "",

    response = Void.class

)};

code：HTTP的状态码，默认200

int code() default 200;

extensions：扩展属性

Extension[] extensions() default {@Extension(

    properties = {@ExtensionProperty(

    name = "",

    value = ""

)}

)};

@ApiImplicitParams

用在请求的方法上，表示一组参数说明，里面通过ApiImplicitParam配置具体参数。

public @interface ApiImplicitParams {

    ApiImplicitParam[] value();

}

@ApiImplicitParam

用在请求的方法上，表示单个参数说明；或者用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

name：参数名

String name() default "";

value：参数说明解释

String value() default "";

defaultValue：参数的默认值

String defaultValue() default "";

allowableValues：

String allowableValues() default "";

required：参数是否必传 true | false，默认false

boolean required() default false;

access：

String access() default "";

allowMultiple：

boolean allowMultiple() default false;

dataType：参数类型，默认String，只作为标志说明，不做实际验证，String和Long

String dataType() default "";

dataTypeClass：

Class<?> dataTypeClass() default Void.class;

paramType：查询参数位置

　　header：请求参数放置于 Header，使用@RequestHeader获取

　　query：请求参数放置于请求地址后边，使用@RequestParam获取

　　path：请求参数放置于请求地址路径中，使用@PathVariable获取

　　body：以流的形式提交参数，仅支持POST

　　form：以form表单的形式提交参数，仅支持POST

String paramType() default "";

example：

String example() default "";

examples：

Example examples() default @Example({@ExampleProperty(

    mediaType = "",

    value = ""

)});

type：

String type() default "";

format：

String format() default "";

allowEmptyValue：

boolean allowEmptyValue() default false;

readOnly：

boolean readOnly() default false;

collectionFormat：

String collectionFormat() default "";

@ApiParam

public @interface ApiParam {

    String name() default "";

    String value() default "";

    String defaultValue() default "";

    String allowableValues() default "";

    boolean required() default false;

    String access() default "";

    boolean allowMultiple() default false;

    boolean hidden() default false;

    String example() default "";

    Example examples() default @Example({@ExampleProperty(

    　　mediaType = "",

    　　value = ""

　　 )});

    String type() default "";

    String format() default "";

    boolean allowEmptyValue() default false;

    boolean readOnly() default false;

    String collectionFormat() default "";

}

@ApiModel

一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候，用于对类进行说明，描述一个Model的信息，表示参数用实体类接收。

public @interface ApiModel {

    String value() default "";

    String description() default "";

    Class<?> parent() default Void.class;

    String discriminator() default "";

    Class<?>[] subTypes() default {};

    String reference() default "";

}

@ApiModelProperty

注解用于方法、字段，表示对model属性的说明或者数据操作更改，配合ApiModel一起使用。

public @interface ApiModelProperty {

    String value() default "";

    String name() default "";

    String allowableValues() default "";

    String access() default "";

    String notes() default "";

    String dataType() default "";

    boolean required() default false;

    int position() default 0;

    boolean hidden() default false;

    String example() default "";

    boolean readOnly() default false;

    String reference() default "";

    boolean allowEmptyValue() default false;

}

@ApiResponses

用在请求的方法上，表示一组响应

public @interface ApiResponses {

    ApiResponse[] value();

}

@ApiResponse

用在@ApiResponses中，一般用于表达一个错误的响应信息

public @interface ApiResponse {

    int code();

    String message();

    Class<?> response() default Void.class;

    String reference() default "";

    ResponseHeader[] responseHeaders() default {@ResponseHeader(

    　　name = "",

    　　response = Void.class

　　)};

    String responseContainer() default "";

}

@ApiIgnore

用在Controller类或者接口方法上，表示该类或者接口被忽略，不在接口文档显示

public @interface ApiIgnore {

  //简要说明为何忽略此参数/操作

  String value() default "";

}

问题

目前了解到的是Swagger不支持直接获取JSONObject和Map类型的参数，这种参数内部字段不可知，文档显示不出来

如果不想封装为一个Model的话可以参考下面的博客实现下，自定义一个注解。

https://blog.csdn.net/cy921107/article/details/82761575 JSONObject

https://blog.csdn.net/hellopeng1/article/details/82227942 Map

示例

package com.erp.server.controller;

import com.alibaba.fastjson.JSONObject;

import com.erp.server.model.User;

import com.erp.server.service.TestService;

import com.erp.server.utils.Constants;

import com.erp.server.utils.result.ResultBuilder;

import com.erp.server.utils.result.StatusCode;

import io.swagger.annotations.*;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.web.bind.annotation.*;

import springfox.documentation.annotations.ApiIgnore;

@Api(tags = {"测试接口类"})

@RestController

@RequestMapping(value = "/api/test")

public class TestController {

    private static final Logger logger = LoggerFactory.getLogger(TestController.class);

    @Autowired

    private TestService testService;

    @ApiIgnore

    @ApiOperation(value = "测试Hello", notes = "一个测试的hello接口")

    @GetMapping("/hello")

    public String hello(){

        return  "Hello Spring Boot";

    }

    @ApiOperation(value = "查询用户", notes = "根据ID查询用户")

    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path", dataType = "integer")

    @GetMapping("/user/{id}")

    public ResultBuilder<User> user(@PathVariable("id")Integer id){

        User user = testService.getUserById(id);

        return new ResultBuilder<User>(user, StatusCode.SUCCESS);

    }

    @ApiOperation(value = "查询用户", notes = "根据ID和姓名查询用户")

    @ApiImplicitParams({

            @ApiImplicitParam(name = "token", value = "用户凭证", required = true, paramType = "header", dataType = "String"),

            @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "query", dataType = "integer"),

            @ApiImplicitParam(name = "name", value = "用户名", required = true, paramType = "query", dataType = "String")

    })

    @GetMapping("/user/id/name")

    public ResultBuilder<User> user1(@RequestHeader("token")String token,

                                     @RequestParam("id")Integer id,

                                     @RequestParam("name")String name){

        logger.debug("token:{},id：{},name：{}", token, id, name);

        User user = testService.getUserById(id);

        return new ResultBuilder<User>(user, StatusCode.SUCCESS);

    }

    @ApiOperation(value = "添加用户", notes = "使用JSON数据添加用户")

    @ApiImplicitParam(name = "jsonObject", value = "用户数据", required = true, paramType = "body",

       examples = @Example(value = @ExampleProperty(mediaType = "application/json", value = "{'id':'','name':'','age':''}"))

            )

    @PostMapping("/user/add/")

    public ResultBuilder<User> adduser(@RequestBody JSONObject jsonObject){

        logger.debug(jsonObject.toJSONString());

        Integer id = jsonObject.getInteger("id");

        User user = testService.getUserById(id);

        return new ResultBuilder<User>(user, StatusCode.SUCCESS);

    }

    @ApiOperation(value = "添加用户", notes = "使用对象数据添加用户")

    @ApiImplicitParam(name = "user", value = "用户数据", required = true, paramType = "body", dataType = "User")

    @PostMapping("/user/add1/")

    public ResultBuilder<User> adduser1(@RequestHeader(Constants.ACCEPT_VERSION)String acceptVersion,

                                        @RequestBody User user){

        return new ResultBuilder<User>(null, StatusCode.SUCCESS);

    }

}

@Api 使用示例

属性注释

@Api　　使用在接口类上

　　tags　　说明该类的作用，可以在UI界面上看到的内容

示例代码

@Api(tags = {"版本接口类"})

@RestController

@RequestMapping("/api/version")

public class VersionController {

  ......

}

界面显示

@ApiOperation 和 @ApiImplicitParam 使用示例

属性注释

@ApiOperation　　使用在接口方法上

　　value　　接口名

　　notes　　接口注释米描述

@ApiImplicitParams　　表示多个参数的情况，需@ApiImplicitParam配合使用

@ApiImplicitParam　　表示单个参数

　　name　　参数

　　value　　参数描述

　　required　　参数是否必须，默认false

　　dataType　　参数类型，这个一般还是别写了，经常写了导致无法使用

　　paramType　　参数位置　　

　　　　header：请求参数放置于 Header，使用@RequestHeader获取

　　　　query：请求参数放置于请求地址后边，使用@RequestParam获取

　　　　path：请求参数放置于请求地址路径中，使用@PathVariable获取

　　　　body：以流的形式提交参数，仅支持POST

　　　　form：以form表单的形式提交参数，仅支持POST

示例代码

    @ApiOperation(value = "采购单列表", notes = "用于查询采购单列表")

    @ApiImplicitParams({

            @ApiImplicitParam(name = "pageNum", value = "查询的页码，默认1", required = false, paramType = "query"),

            @ApiImplicitParam(name = "pageSize", value = "每页显示条数，默认10", required = false, paramType = "query"),

            @ApiImplicitParam(name = "wareId", value = "采购ID", required = false, paramType = "query"),

            @ApiImplicitParam(name = "startTime", value = "开始时间，毫秒数", required = false, paramType = "query"),

            @ApiImplicitParam(name = "endTime", value = "结束时间，毫秒数", required = false, paramType = "query"),

            @ApiImplicitParam(name = "wareStatus", value = "采购单状态。-1：删除，0：正常", required = false, paramType = "query"),

            @ApiImplicitParam(name = "wareType", value = "采购类型：0：入库单，1：退货单", required = false, paramType = "query")

    })

    @GetMapping("/list")

    public ResultBuilder getWareHouseList(@RequestHeader(Constants.VERSION_CODE)Integer versionCode,

                                          @RequestHeader(Constants.ACCESS_TOKEN)String token,

                                          @RequestParam(value = "pageNum", required = false)Integer pageNum,

                                          @RequestParam(value = "pageSize", required = false)Integer pageSize,

                                          @RequestParam(value = "wareId", required = false)String wareId,

                                          @RequestParam(value = "startTime", required = false)Long startTime,

                                          @RequestParam(value = "endTime", required = false)Long endTime,

                                          @RequestParam(value = "wareStatus", required = false)Integer wareStatus,

                                          @RequestParam(value = "wareType", required = false)Integer wareType){

        return wareHouseService.getWareHouseList(pageNum, pageSize, wareId, startTime, endTime, wareStatus, wareType);

    }

界面显示

@ApiModel 和 @ApiModelProperty 使用示例

属性注释

@ApiModel 使用在实体类上

　　value　　实体类名称

　　description　　实体类描述信息

@ApiModelProperty 使用在实体类中字段上

　　value　　字段名

　　required　　　字段是否必须，默认false

　　hide　　字段是否隐藏，默认false

　　example　　字段值示例

示例代码

实体类

@ApiModel(value = "软件版本", description = "这里是描述信息")

public class Version {

    @ApiModelProperty(value = "版本", required = true, example = "1.0.0")

    private String version;

    @ApiModelProperty(value = "版本号", required = true)

    private Integer versionCode;

    @ApiModelProperty(value = "最小版本号", required = true)

    private Integer minVersionCode;

    @ApiModelProperty(value = "强制更新标志", required = true)

    private Integer updateForce;

    @ApiModelProperty(value = "更新内容")

    private String updateContent;

    @ApiModelProperty(value = "更新地址", required = true)

    private String updateUrl;

    @ApiModelProperty(hidden = true)

    private Date createTime;

    @ApiModelProperty(hidden = true)

    private Date updateTime;

    省略set/get

}

接口方法

@ApiOperation(value = "新版本检查", notes = "检查APP是否需要进行版本升级")

@PostMapping("/check")

public ResultBuilder versionCheck(@RequestBody Version version){
　　。。。
}

界面显示

Models中也会显示这个Model

巴特西

SpringBoot 集成 Swageer2

添加Maven依赖

添加配置类

注解使用

@Api

@ApiOperation

@ApiImplicitParams

@ApiImplicitParam

@ApiParam

@ApiModel

@ApiModelProperty

@ApiResponses

@ApiResponse

@ApiIgnore

问题

示例

@Api 使用示例

@ApiOperation 和 @ApiImplicitParam 使用示例

@ApiModel 和 @ApiModelProperty 使用示例

最新文章

热门文章