swagger的说明、配置及使用

 

一、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(); } }

//第二种配置类

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger {

@Bean
public Docket appApi() {
return new Docket(DocumentationType.SWAGGER_2).enable(true)
.groupName("appApi")
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(true)
.pathMapping("/")// base，最终调用接口后会和paths拼接在一起
.select()
// .paths(or(regex("/.*")))//过滤的接口
.build()
.apiInfo(appApiInfo());
}
private ApiInfo appApiInfo() {
return new ApiInfoBuilder()
.title("嘻嘻哈哈")
.description("小系统")
.version("1.0")
.build();
}
}

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

转载于:https://www.cnblogs.com/Daisyisme/p/9777101.html