关闭

SpringMVC开发——使用Swagger搭建接口请求页面

标签: spring mvcSwagger
2062人阅读 评论(1) 收藏 举报
分类:
        Swagger是一款RESTful接口的文档在线自动生成模板和页面,使用和平台以及语言无关。目前在很多公司以及实际项目中大量用到。可以把Swagger理解为接口文档,后台写好的代码可以直接生成前端接口文档页面,接口调用这可以通过这个页面发送接口请求,进行接口测试或调用。使用起来非常方便。使用了Swagger之后,就不需要再去维护其他的接口文档了,节省了很多的成本。本文使用的项目案例上传至  https://github.com/chenyufeng1991/StartSpringMVC.git 。本文将会来介绍如何搭建一个完整的Swagger框架。Swagger的官方地址为:http://swagger.io/。一个简答的Swagger页面如下图所示:


(1)Swagger在Github上的地址为:https://github.com/swagger-api/swagger-ui  。大家可以下载该项目,然后把dist目录下的所有内容都加入到自己项目的webapp目录下。大家也可以下载我的StartSpringMVC项目,把webapp目录下的css、images、lib、index.html和swagger-ui.js导入到自己的项目中即可。其中显示的前端页面就是index.html.



(2)然后需要在项目中新加一个类,作为swagger的配置文件,我在StartSpringMVC中的类是“CustomJavaPluginConfig”,该类的实现如下:

@Configuration
@EnableWebMvc
@EnableSwagger
public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {

    private SpringSwaggerConfig springSwaggerConfig;

    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo()).includePatterns(".*")
                .useDefaultResponseMessages(false)
                // .pathProvider(new GtPaths())
                .apiVersion("0.1").swaggerGroup("user");

    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo("我的RESTful接口平台",
                "提供详细的后台所有Restful接口", "http://blog.csdn.net/chenyufeng1991",
                "yufengcode@gmail.com", "乞力马扎罗的雪-博客", "http://blog.csdn.net/chenyufeng1991");
        return apiInfo;
    }

    @Override
    public void configureDefaultServletHandling(
            DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }

    class GtPaths extends SwaggerPathProvider {

        @Override
        protected String applicationPath() {
            return "/restapi";
        }

        @Override
        protected String getDocumentationPath() {
            return "/restapi";
        }
    }
}



(3)对于一个实体模型,需要使用swagger去标识。如下面的Student模型,其中的@ApiModel、@ApiModelProperty都是属于Swagger的注解。如果需要在接口中返回模型对象,则需要使用以下的方式去注解。

@ApiModel(value = "学生对象", description = "student")
public class Student {

    @ApiModelProperty(value = "姓名", required = true)
    String name;
    @ApiModelProperty(value = "年龄", required = true)
    String age;

    public Student(String name, String age) {
        this.name = name;
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAge() {
        return age;
    }

    public void setAge(String age) {
        this.age = age;
    }
}



(4)在进行接口设计的Controller中,同样需要使用Swagger注解。其中下面的@Api、@ApiOperaction、@Apiparam都是Swagger注解,其中@Api表示这是一个需要Swagger表示的类;@ApiOperaction表示这是一个需要Swagger修饰的接口,其中表明了请求方式、说明等信息。@ApiParam表示该接口输入的参数,value是参数的值说明,required表示该参数是否是必须的。

@Api(value = "football", description = "足球", produces = MediaType.APPLICATION_JSON_VALUE)
@Controller
@RequestMapping("football")
public class FootballController {

    @ApiOperation(value = "用户登录注册", notes = "用户", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "user", method = RequestMethod.GET)
    public List<Student> foo(
            @ApiParam(value = "用户名", required = true) @RequestParam String name,
            @ApiParam(value = "年龄", required = true) @RequestParam String age
    ) {
        //获取请求的参数,需要和链接中的参数名一致
        //推荐使用HttpServletRequest的方式来获取参数,GET、POST的参数都可以接收
        List<Student> list = new ArrayList<Student>();

        Student student = new Student(name, age);
        Student student1 = new Student(name + name, age + age);
        list.add(student);
        list.add(student1);
        return list;
    }

    @ApiOperation(value = "用户登录注册2", notes = "用户2", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
    @ResponseBody
    @RequestMapping(value = "customer/login", method = RequestMethod.POST)
    public String foo2(
            @ApiParam(value = "用户名", required = true) @RequestParam String name
    ) {
        return name;
    }
}



(5)重要的是,要在pom.xml中加入swagger的依赖:

<!-- Swagger-mvc -->
<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.2</version>
</dependency>



(6)完成后的运行界面如下图所示。大家可以根据自己的实际需求自定义页面元素。





2
0
查看评论
发表评论
* 以上用户言论只代表其个人观点,不代表CSDN网站的观点或立场

基于swagger的RESTful API

基于swagger的RESTful API摘要: 前言 RESTful架构,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。后端通过提供一套标...
  • Derekwh
  • Derekwh
  • 2016-07-01 16:59
  • 6628

Swagger与RestFul 集成 以及 注解使用Demo

准备工作: 1 按文档搭建Spring Boot 和 Swagger: http://www.cnblogs.com/xiaohanghang/p/6018654.html 另附标准RestFul ...
  • jun55xiu
  • jun55xiu
  • 2017-04-21 15:45
  • 10207

Restful形式接口文档生成之Swagger与SpringMVC整合手记

笔者目前正在搭建一套API服务框架,考虑到客户端能够更方便的调用API服务(这里说的更方便是指避免不厌其烦地解说各接口需要的参数和返回结果),于是决心为每个接口生成详细的说明文档。网上搜索了一下,发现...
  • linlzk
  • linlzk
  • 2016-02-24 10:21
  • 33722

Swagger2 添加HTTP head参数

大家使用swagger往往会和JWT一起使用,而一般使用jwt会将token放在head里,这样我们在使用swagger测试的时候并不方便,因为跨域问题它默认不能自定义head参数。然后自己去网上找,...
  • u014044812
  • u014044812
  • 2017-05-09 15:19
  • 7494

Swagger--连接前后端的通道

前后端分离 按照现在的趋势,前后端分离几乎已经是业界对开发和部署方式所达成的一种共识。所谓的前后端分离,并不是传统行业中的按部门划分,一部分人只做前端(HTML/CSS/JavaScript等等...
  • jansony1
  • jansony1
  • 2016-06-13 15:29
  • 590

Swagger UI 隐藏指定接口类或方法

Swagger UI 隐藏指定接口类或方法
  • lqh4188
  • lqh4188
  • 2016-12-09 14:24
  • 6152

maven 项目(五) spring集成springMVC开发统一接入API--实现test接口

为什么要采用测试接口的方式:贴完代码我再来说; 1.贴张图片 2.是测试接口地址的暴露方式: @Controller public class ApiTestController { ...
  • u010235716
  • u010235716
  • 2016-04-19 15:38
  • 2296

SpringMVC 开发接口

上篇文章讲解了SpringMVC 入门,这篇文章使用SpringMVC 来开发接口。记得之前有一篇文章 java web开发(二) 接口开发,是使用Servlet开发的接口。如果你还未了解,可以先看...
  • zxw136511485
  • zxw136511485
  • 2016-09-22 22:21
  • 13328

【实践笔记】Spring MVC中Restful API使用 Swagger2 构建

【实践笔记】Spring MVC中Restful API使用 Swagger2 构建
  • Zhaky
  • Zhaky
  • 2017-03-22 11:37
  • 3440

手把手带你入门之Swagger UI

关于Swagger UI,从官网找来一段介绍。 简单的来讲, Swagger UI就是API文档生成和测试利器。 Swagger UI is a dependency-freecollection o...
  • chndata
  • chndata
  • 2016-01-04 15:33
  • 8077
    个人资料
    • 访问:2326365次
    • 积分:29173
    • 等级:
    • 排名:第205名
    • 原创:660篇
    • 转载:36篇
    • 译文:0篇
    • 评论:523条
    我的微博
    博客专栏
    开源项目
    联系方式
    最新评论