初学swagger的说明、配置及使用

 原文地址:https://blog.csdn.net/weixin_37848710/article/details/80677976

一、What is swagger?

官方介绍Swagger是一个规范且完整的框架,提供描述、生产、消费和可视化RESTful Web Service。
专业角度:Swagger是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二、Why use the swagger?

  1. 讲个故事:在2014年时候,我和另一个小伙伴加入到一个实验室,开始了我们漫长的应用开发之路(这也是第一次做项目)。因为只有两个人,我做后台,他做Android,分工很明确的。在一开始,我们并没有关注API相关的内容,随手拈来,我说什么,他就调用什么。当然,也没有什么API文档提供。以至于到现在,我想更新升级系统,才发现,我们写的代码是有多烂,连自己都不忍心去看的。所以说在项目开始就定一个契约,双方(前端后台)就API相关的内容,包括路径、参数、类型等达成一致,当然,这份契约并不是一旦创建就不能修改的,而且,如果一开始没有设计好,很有可能会频繁的修改。
  2. 作为一个很懒的码代码的猿呢,对于一些API的理解总是很模糊不清,但是,总想着能直接验证一下自己的理解就好了,而不是需要去项目写测试代码来验证自己的想法。所以说,API文档应该有直接运行的能力。而Swagger就是这样的一个东西,它可以为已有项目的生成具备执行能力的样式化API文档,这样可以极大的方便程序员对前端后台进行对接整合。

三、use the swagger

1. 开发环境介绍
  • maven 3.3
  • jdk 8+
  • spring 4.2.5
  • mybatis 3.4.1
  • swagger 1.0.2
2. 在pom.xml文件中添加swagger相关依赖
<!-- swagger-mvc -->
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.6.6</version>
        </dependency>
        <!-- swagger-mvc -->
3. 自定义对swagger的配置

对于swagger的配置,其实对自定义一个与swagger相关的Config类,可以通过Java编码的实现配置。代码如下:

package com.hp.common.swagger;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.paths.SwaggerPathProvider;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**
 * 
 * @ClassName: SwaggerConfig.java
 * @Description: Swagger配置类
 *
 * @version: v1.1.0
 * @author: xiangdong
 * @date: Mar 16, 2017
 */
public class SwaggerConfig extends WebMvcConfigurerAdapter {

    private SpringSwaggerConfig springSwaggerConfig;

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

    /**
     * 链式编程 来定制API样式 后续会加上分组信息
     * 
     * @return
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){
           return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                    .apiInfo(apiInfo())
                    .includePatterns(".*?");
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo("API接口测试平台",
                "提供后台所有Restful接口", "www.flyeast.top",
                "shexd1001@gmail.com", "β客栈", "www.flyeast.top");
        return apiInfo;
    }

    @Override
    public void configureDefaultServletHandling(
            DefaultServletHandlerConfigurer configurer) {
        configurer.enable();
    }
}
3. 注入SwaggerConfig类

上面这段对swagger进行了基本的配置,现在需要将其注入到spring容器中,完成在程序加载之后对所有接口扫描解析的功能呢,在spring相关的配置文件中加入以下代码:

    <!-- swagger配置信息 -->
    <bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
4. 配置需要解析的接口方法

以下代码是Controller中的一个方法,@ApiOperation注解对这个方法进行了说明,@ApiParam注解对方法参数进行了说明。关于其他注解,可以查看源码或其他帮助文档;

/**
     * DELETE 删除用户
     * @return
     */
    @ApiOperation(value = "删除用户信息", notes = "删除用户", httpMethod = "DELETE", produces = MediaType.APPLICATION_JSON_VALUE)
    @RequiresPermissions("sysuser:list:delete")
    @RequestMapping(value = "/list/{accountId}/delete", method = RequestMethod.DELETE)
    @ResponseBody
    public AjaxResult delete(@PathVariable Long accountId) {
        systemUserService.deleteSysUser(accountId);
        return success(true);
    }
5. 对Swagger-UI进行配置

Swagger扫描解析得到的是一个json文档,所以对于用户使用不是很方便,但是通过swagger-ui,可以友好的展示解析得到的接口说明内容。
这里 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/目录下。
修改index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,我们需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,如http://localhost:8080/CloudTi/api-docs

6. 运行项目,访问URL

URL是自己在index.html中定义的URL



阅读更多
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页

加入CSDN,享受更精准的内容推荐,与500万程序员共同成长!
关闭
关闭