文档章节

Swagger使用 – 世界上最流行的api框架

菜鸟一直在成长
 菜鸟一直在成长
发布于 2017/05/03 21:01
字数 783
阅读 168
收藏 0

#增加依赖

compile('io.springfox:springfox-swagger2:2.6.1')
compile('io.springfox:springfox-swagger-ui:2.6.1')

#配置类

/**
 * Created by nc423 on 2017/4/5.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //扫描包
    @Value(value = "${swagger.api.basePackage}")
    private String basePackage;
    //标题
    @Value(value = "${swagger.api.title}")
    private String title;
    //描述
    @Value(value = "${swagger.api.description}")
    private String description;
    //联系
    @Value(value = "${swagger.api.contact}")
    private String contact;
    //版本
    @Value(value = "${swagger.api.version}")
    private String version;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))//扫描包
                .paths(PathSelectors.any())
                .build();

               // .groupName("g1")
                //.host("10.1.197.85:8080")/
                //pathMapping("/swagger"); // 在这里可以设置请求的统一前缀;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(contact)
                .version(version)
                .build();
    }*/


}

#自定义json输出url

#自定义api输出url。 JSON格式  默认 /v2/api-docs
springfox.documentation.swagger.v2.path=/swagger.json

#常用注解

@ApiIgnore 忽略注解标注的类或者方法,不添加到API文档中
@Api:用在类上,说明该类的作用
@ApiOperation:用在方法上,说明方法的作用
    value api名称
    notes 备注说明
@ApiImplicitParams:用在方法上包含一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    name 对应方法中接收参数名称
    value 备注说明
    required 是否必须 布尔
    paramType:参数类型 body、path、query、header、form中的一种 (参数放在哪儿)
        path(用于restful接口)在url中配置{}的参数-->请求参数的获取:@PathVariable
        header-->请求参数的获取:@RequestHeader
        query-->请求参数的获取:@RequestParam,springMvc一般不需要
        body(不常用)使用@RequestBody接收数据 POST有效
        form(不常用)查看官方API文档
    dataType:参数类型
    required:参数是否必须传
    defaultValue:参数的默认值
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
    code:数字,例如400
    message:信息,例如"请求参数没填好"
    response:抛出异常的类
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:描述一个model的属性。例:@ApiModelProperty(dataType = "com.qualified.ReplacedWith")
@ApiParam 对单独某个参数进行说明,使用在类中或者controller方法中都可以。注解中的属性和上面列出的同名属性作用相同

#junit ###需要增加依赖

compile 'org.asciidoctor:asciidoctorj:1.5.4'
compile "io.github.swagger2markup:swagger2markup:1.3.1"
testCompile ('io.springfox:springfox-staticdocs:2.6.1')
testCompile('org.springframework.boot:spring-boot-starter-test')
import io.github.robwin.markup.builder.MarkupLanguage;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.SpringApplicationConfiguration;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
import org.springframework.test.web.servlet.result.MockMvcResultMatchers;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import springfox.documentation.staticdocs.Swagger2MarkupResultHandler;
import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

/**
 * Created by nc423 on 2017/4/6.
 *
 */
@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = SwaggerApplication.class)
public class ApiTest {

    @Autowired
    private WebApplicationContext context;

    private MockMvc mockMvc;

    @Before
    public void setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();

    }

    /**
     * 生成asciidoc格式文件
     * @throws Exception
     */
    @Test
    public void convertSwaggerToAsciiDoc() throws Exception {
        this.mockMvc.perform(MockMvcRequestBuilders.get("/swagger.json")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(Swagger2MarkupResultHandler.outputDirectory("src\\docs\\asciidoc\\generated").build())
                .andExpect(MockMvcResultMatchers.status().isOk());
    }

    /**
     * 生成markdown格式文件
     * @throws Exception
     */
    @Test
    public void convertSwaggerToMarkdown() throws Exception {
        this.mockMvc.perform(MockMvcRequestBuilders.get("/swagger.json")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(Swagger2MarkupResultHandler.outputDirectory("src\\docs\\asciidoc\\generated")
                        .withMarkupLanguage(MarkupLanguage.MARKDOWN).build())
                .andExpect(MockMvcResultMatchers.status().isOk());
    }

    /**
     * 生成json格式文件
     * @throws Exception
     */
    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
        String outputDir = "src\\docs\\asciidoc\\generated";  //将api-docs的json数据写入文件
        MvcResult mvcResult = this.mockMvc.perform(MockMvcRequestBuilders.get("/swagger.json")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andReturn();
        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }



}

© 著作权归作者所有

菜鸟一直在成长
粉丝 5
博文 43
码字总数 18676
作品 0
丰台
私信 提问
C# WebAPI中使用Swagger

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系,变成了API接口...

peterYong
2018/09/01
0
0
Spring Boot集成Swagger简易教程

Swagger   Swagger号称是史上最流行的、最好用的API接口文档构建工具,它支持多种语言包括Java在内,本文仅关注如何使用Spring Boot来集成Swagger,更多关于Swagger的介绍可以查看以下几个...

mario阿东
2018/06/26
0
0
spring boot 整合swagger2 实现动态生成接口文档

背景介绍 在以往的项目开发中,项目的接口文档一般以word的形式,互相传阅。但是具有以下缺点: 1.接口更新了,文档没更新 2.系统版本多,接口版本也很多,不好管理 3.测试接口时,通常会使用...

杨健-YJ
01/08
0
0
Linux 基金会联合谷歌微软推出“开放 API 战略”

近日,Linux 基金会宣布推出“开放 API 战略”( Open API Initiative )以促成一个更加广泛、开放的 API 标准,创始成员包括谷歌、微软、IBM 等科技巨头,这项战略基于现有的 Swagger (已收...

oschina
2015/11/07
3.3K
6
swagger2常用注解说明

说明: 1.这里使用的版本:springfox-swagger2(2.4)springfox-swagger-ui (2.4) 2.这里是说明常用注解的含义和基本用法(也就是说已经对swagger进行集成完成) 没有集成的请参见 Spring...

u014231523
2017/08/01
0
0

没有更多内容

加载失败,请刷新页面

加载更多

定时获取服务器时间戳的一个类(Typescript)

export class TimeStampService { private _localTimestamp: number; // 本地时间戳 private _serveTimestamp: number; // 服务器端时间戳 private _duration: number = 1000 ......

lilugirl
33分钟前
1
0
前段技术总结

前端UI框架组件库: 说到前端框架我第一印象中想起React、Vue和Angular,不知道你是否与我一样想到这些,现在常用的有:Bootstrap、jQuery UI、BootMetro、AUI常用的还有很多、就不一一跟大家...

WinkJie
52分钟前
1
0
对话亲历者|鲁肃:我在支付宝“拧螺丝“的日子

摘要: 他是支付宝技术平台的奠基人之一,但是他总说“这还不是我心中最完美的架构”;他行事低调但却有着“此时此地,非我莫属”的豪气;他曾无数次充当救火大队长,但自评只是“没有掉队的...

阿里云云栖社区
今天
7
0
设置 npm yarn 淘宝源

设置npm config set chromedriver_cdnurl=http://cdn.npm.taobao.org/dist/chromedriver设置yarn config set "chromedriver_cdnurl" "https://npm.taobao.org/mirrors/chromedriver"......

internetafei
今天
2
0
Docker搭建Mysql集群、主从同步复制

1、创建数据挂载点: mkdir /opt/mysql-master/mysql、/opt/mysql-master/conf.d、/opt/mysql-slave/mysql、/opt/mysql-slave/conf.d 2、分别在master、slave节点文件目录conf.d下创建touch......

WALK_MAN
今天
16
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部