springBoot（15）：集成Swagger

一、简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。http://swagger.io/

Springfox 的前身是swagger-springmvc，是一个开源的API doc框架，可以将我们的 Controller的方法以文档的形式展现，基于Swagger。http://springfox.github.io/springfox/

二、操作

2.1、添加依赖

1
2
3
4
5
6
7
8
9
10
11

<!-- Swagger -->

<dependency>

   <groupId>io.springfox</groupId>

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

   <version>2.6.0</version>

</dependency>

<dependency>

   <groupId>io.springfox</groupId>

   <artifactId>springfox-swagger2</artifactId>

   <version>2.6.0</version>

</dependency>

2.2、代码

package com.example.demo.utils.configuration;
 
import static springfox.documentation.builders.PathSelectors.regex;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

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;
 
/**

 * Swagger配置

 * @Author: 我爱大金子

 * @Description: Swagger配置

 * @Date: Create in 11:33 2017/6/22

 */
@Configuration
@EnableSwagger2

public class Swagger2Configuration {

    @Bean

    public Docket accessToken() {

        return new Docket(DocumentationType.SWAGGER_2).groupName("index")// 定义组

                .select() // 选择那些路径和 api 会生成 document

                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 拦截的包路径

                .paths(regex("/index/.*"))// 拦截的接口路径

                .build() // 创建

                .apiInfo(apiInfo()); // 配置说明

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()//

                .title("测试")// 标题

                .description("spring boot 全集")// 描述

                .termsOfServiceUrl("http://www.roncoo.com")//

                .contact(new Contact("我爱大金子", "http://1754966750.blog.51cto.com/", "[email protected]"))// 联系

                // .license("Apache License Version 2.0")// 开源协议

                // .licenseUrl("https://github.com/springfox/springfox/blob/master/LICENSE")// 地址

                .version("1.0")// 版本

                .build();

    }
}

测试用的Controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

@RestController

@RequestMapping("/index")

public class IndexController {

    @Autowired

    private UserMapper mapper;
 

    @RequestMapping(value = "/index", method = RequestMethod.POST)

    public Map<String, Object> index(Integer id) throws Exception {

        Map<String, Object> map = new HashMap<String, Object>();

        User user = mapper.selectByPrimaryKey(id);

        if (null != user) {

            map.put("id", user.getId());

            map.put("name", user.getName());

        } else {

            map.put("id", -1);

            map.put("name", "error");

        }

        return map;

    }
}

效果：访问http://localhost:8989/swagger-ui.html

2.3、自定义(注解的使用)

@ApiIgnore

忽略暴露的 api

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

添加说明

其他注解：

@Api ：用在类上，说明该类的作用

@ApiImplicitParams ：用在方法上包含一组参数说明

@ApiResponses ：用于表示一组响应

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

code：数字，例如 400

message：信息，例如"请求参数没填好"

response：抛出异常的类

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

@ApiModelProperty ：描述一个 model 的属性

本文转自我爱大金子博客51CTO博客，原文链接http://blog.51cto.com/1754966750/1940912如需转载请自行联系原作者

我爱大金子

springBoot（15）：集成Swagger

相关推荐