springboot系列十三、springboot集成swaggerUI

2022-12-06 20:04:26

一、Swagger介绍

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

二、配置及使用Swagger

1、引入依赖

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.7.0</version>

</dependency>

    <dependency>

    <groupId>io.springfox</groupId>

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

    <version>2.7.0</version>

</dependency>

2、添加配置类：SwaggerConfig.java

package com.example.demo.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;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

 * Swagger2配置类

 * 在与spring boot集成时，放在与Application.java同级的目录下。

 * 通过@Configuration注解，让Spring来加载该类配置。

 * 再通过@EnableSwagger2注解来启用Swagger2。

 */

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    /**

     * 创建API应用

     * apiInfo() 增加API相关信息

     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，

     * 本例采用指定扫描的包路径来定义指定要建立API的目录。

     *

     * @return

     */

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))

                .paths(PathSelectors.any())

                .build();

    }

    /**

     * 创建该API的基本信息（这些基本信息会展现在文档页面中）

     * 访问地址：http://项目实际地址/swagger-ui.html

     * @return

     */

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                .title("Spring Boot中使用Swagger2构建RESTful APIs")

                .description("更多请关注:博客园小人物的奋斗")

                .termsOfServiceUrl("http://www.cnblogs.com/wangzhuxing")

                .contact("xing")

                .version("1.0")

                .build();

    }

}

3、使用示例

1、注解Controller类

@Controller

@RequestMapping("/User")

@Api(description = "测试swagger注解的demo")

public class HelloWorldController {

　　@ResponseBody
　　@RequestMapping(value = "/getAllUser" ,method = RequestMethod.POST)
　　@ApiOperation(value = "获取用户信息",notes = "返回单个用户信息")
　　public List<UserPO> getAllUser(@ApiParam(required = false) @RequestBody User user) {
    　　userService.addUser();
    　　return userService.findAll();
　　}

2、注解入参和出参

package com.example.demo.bean;

import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

public class User implements Serializable {

    @ApiModelProperty(value = "用户id" ,example = "11")

    private Long uid;

    @ApiModelProperty(value = "用户姓名",example = "小明")

    private String name;

    @ApiModelProperty(value = "用户年龄",example = "25")

    private Integer age;

    public Long getUid() {

        return uid;

    }

    public void setUid(Long uid) {

        this.uid = uid;

    }

    public String getName() {

        return name;

    }

    public void setName(String name) {

        this.name = name;

    }

    public Integer getAge() {

        return age;

    }

    public void setAge(Integer age) {

        this.age = age;

    }

}

4、验证效果

访问：http://192.168.1.100:8080/swagger-ui.html

三、常见用法和说明

@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

l @ApiModelProperty：描述一个model的属性
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

l code：数字，例如400

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

　　l response：抛出异常的类

Swagger是一组开源项目，其中主要要项目如下：

1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3. Swagger-js: 用于JavaScript的Swagger实现。

4. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

码农公寓