如何在SpringBoot里使用SwaggerUI

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了如何在SpringBoot里使用SwaggerUI相关的知识,希望对你有一定的参考价值。

参考技术A Swagger-UI纯碎的基于html+javascript实现,在.NET中应用,也就是在 asp.net 页面中应用相应的 js,按照规范写 html 就可以了。 有一个Swagger.Net.UI 你可以搜索一下。 参考技术B demo地址:demo-swagger-springboot
springboot中swaggerUI的使用

1.pom文件中添加swagger依赖
2.从github项目中下载swaggerUI
然后把dist目录下的所有文件复制到springboot项目的webapp下面,修改index.html中的: url = "http://petstore.swagger.io/v2/swagger.json";为---------> url="http://localhost:8080/api-docs";

3.spring boot启动类
public static void main(String[] args)
SpringApplication.run(IndexController.class,args);

/** 配置 swagger开始*/ private SpringSwaggerConfig springSwaggerConfig;

/**
* Required to autowire SpringSwaggerConfig
*/
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
this.springSwaggerConfig = springSwaggerConfig;


/**
* Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
* framework - allowing for multiple swagger groups i.e. same code base
* multiple swagger resource listings.
*/
@Bean
public SwaggerSpringMvcPlugin customImplementation()
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");


private ApiInfo apiInfo()
ApiInfo apiInfo = new ApiInfo(
"测试接口文档(标题)", // App Service API
"这是一个描述信息。。。",
"termsOfServiceUrl",
"younaame@yourmail.com",
"2222222222222222222222222222",
"3333333333333333333333333333");
return apiInfo;

/** 配置 swagger结束*/

4. 添加测试rest接口类:
@RestController
public class HelloController

@RequestMapping(value = "/hello")
@ApiOperation(value = "添加用户",httpMethod ="POST", response = User.class,notes = "HelloWorld")
public User hello(@ApiParam(required = true,name = "paramData",value = "用户信息 json 数据") String paramData)
User userBean = new User();
userBean.setName("测试用户"); userBean.setOtherInfo("其他信息"); return userBean;

5 访问http://localhost:8080/api-docs,返回:

"apiVersion": "1.0",
"apis": [

"description": "Basic Error Controller",
"path": "/default/basic-error-controller",
"position": 0
,

"description": "Hello Controller",
"path": "/default/hello-controller",
"position": 0

],
"authorizations":

,
"info":
"contact": "younaame@yourmail.com",
"description": "这是一个描述信息。。。",
"license": "2222222222222222222222222222",
"licenseUrl": "3333333333333333333333333333",
"termsOfServiceUrl": "termsOfServiceUrl",
"title": "测试接口文档(标题)"
,
"swaggerVersion": "1.2"
说明配置正确。 然后再访问:http://localhost:8080/swagger/index.html,查看restful风格接口信息和效果。

springboot系列十springboot集成swaggerUI

一、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

 三、常见用法和说明

  1. @Api:用在类上,说明该类的作用。
  2. @ApiOperation:注解来给API增加方法说明。
  3. @ApiImplicitParams : 用在方法上包含一组参数说明。
  4. @ApiImplicitParam:用来注解来给方法入参增加说明。
  5. @ApiResponses:用于表示一组响应
  6. @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)

        l   @ApiModelProperty:描述一个model的属性

  7. @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资源声明以各种语言生成客户端代码。

 

以上是关于如何在SpringBoot里使用SwaggerUI的主要内容,如果未能解决你的问题,请参考以下文章

Springboot:Swagger UI 格式在 AWS 中显示不正确

SpringBoot/Git/Linux/EasyCode

解决访问swaggerUI接口文档显示basic-error-controler问题

再见丑陋的 SwaggerUI,这款开源的API文档生成神器界面更炫酷,逼格更高!

再见丑陋的 SwaggerUI,这款开源的API文档生成神器界面更炫酷,逼格更高

Spring Boot + Swagger + Swagger UI 和 @RequestBody 具有数据类型 String