1. Swagger UI

按以下步骤配置,项目启动后访问:
http://localhost:8080/swagger-ui.html

1.1 添加依赖

    <dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

1.2 配置类

@Configuration
@EnableSwagger2
public class Swagger2 { public static final String SWAGGER_SCAN_BASE_PACKAGE = "abc.boot.examples.web";
public static final String VERSION = "1.0.0"; @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//api接口包扫描路径
.paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档,忽略哪些请求
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2 接口文档示例")//设置文档的标题
.description("更多内容请关注:http://www.abc.com")//设置文档的描述->1.Overview
.version(VERSION)//设置文档的版本信息-> 1.1 Version information
.contact(new Contact("ABC Boot", "http://www.abc.comt", ""))//设置文档的联系方式->1.2 Contact information
.termsOfServiceUrl("www.abc.com")//设置文档的License信息->1.3 License information
.build();
}
}

1.3 注解使用

@ApiOperation

@ApiOperation(value="获取用户列表", notes="获取所有用户列表",produces = "application/json")
@RequestMapping(value="/users", method= RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}

@ApiResponses

@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息",produces = "application/json")
// ApiResponses 增加返回结果的描述
@ApiResponses(value = {@ApiResponse(code = 405,message = "Invalid input",response = Integer.class)}) (1)
@ApiImplicitParam(name = "id",value = "用户ID",dataType = "int",paramType = "path") (2)
@RequestMapping(value="/users/{id}", method= RequestMethod.GET)
public User getUser(@PathVariable Integer id) {
return users.get(id);
}

(1) 在默认Response的基础上增加新的Response说明
(2) 使用ApiImplicitParam描述接口参数

@ApiImplicitParams

@ApiOperation(value="更新用户名称", notes="更新指定用户的名称")
@RequestMapping(value="/users/{id}", method= RequestMethod.POST)
@ApiImplicitParams({ (1)
@ApiImplicitParam(name = "id",value = "用户ID",paramType = "path",dataType = "int"), (2)
@ApiImplicitParam(name = "userName",value = "用户名称",paramType = "form",dataType = "string")
})
public void updateUserName(@PathVariable Integer id,@RequestParam String userName){
User u = users.get(id);
u.setName(userName);
}

(1) 使用ApiImplicitParams描述多个参数
(2) 使用ApiImplicitParam时,需要指定paramType,这样也便于swagger ui 生成参数的输入格式。

paramType 有五个可选值 : path, query, body, header, form

@ApiParam

@ApiOperation(value="创建用户-传递简单对象", notes="传递简单对象",produces = "application/json")
@RequestMapping(value="/users-1", method= RequestMethod.POST)
//可以不加ApiParam注解,需要给参数添加描述时可以使用这个注解,或者使用ApiImplicitParams注解 (1)
public Map postUser(@RequestParam String userName,@ApiParam("地址") @RequestParam(required = false) String address) {
User user = new User();
user.setId(Math.round(10));
user.setName(userName);
user.setAddress(address);
users.put(user.getId(), user);
return ImmutableMap.of("user",user);
}

(1) 使用ApiParam描述接口参数

ApiImplicitParam 与 ApiParam 的区别
ApiImplicitParam: This is the only way to define parameters when using Servlets or other non-JAX-RS environments.

  • 对Servlets或者非 JAX-RS的环境,只能使用 ApiImplicitParam。
  • 在使用上,ApiImplicitParam比ApiParam具有更少的代码侵入性,只要写在方法上就可以了,但是需要提供具体的属性才能配合swagger ui解析使用。
  • ApiParam只需要较少的属性,与swagger ui配合更好。

传递复杂对象 By ModelAttribute

@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO, url参数拼接",produces = "application/json")
@RequestMapping(value="/users-2", method= RequestMethod.POST)
//传递对象推荐使用ModelAttribute注解
public Map postUser2(@ModelAttribute User user) { (1)
users.put(user.getId(),user);
return ImmutableMap.of("user",user);
}

(1) ModelAttribute 是Spring mvc的注解,这里Swagger可以解析这个注解,获得User的属性描述

@ApiModel

@ApiModel(value = "User", description = "用户对象")
public class User { @ApiModelProperty(value = "ID")
private Integer id;
@ApiModelProperty(value = "姓名")
private String name;
@ApiModelProperty(value = "地址")
private String address;
@ApiModelProperty(value = "年龄",access = "hidden")
private int age;
@ApiModelProperty(value = "性别")
private int sex;
.......
}

传递复杂对象 By RequestBody

@ApiOperation(value="创建用户-传递复杂对象", notes="传递复杂对象DTO,json格式传递数据",produces = "application/json")
@RequestMapping(value="/users-3", method= RequestMethod.POST)
//json格式传递对象使用RequestBody注解
public User postUser3(@RequestBody User user) {
users.put(user.getId(),user);
return user;
}

PathVariable

@ApiOperation(value="删除用户- PathVariable", notes="根据url的id来指定删除对象")
@RequestMapping(value="/users/{id}", method = RequestMethod.DELETE)
public void deleteUser(@PathVariable Integer id) { (1)
users.remove(id);
}

(1) PathVariable是Spring 的注解,对于这种简单的参数,就可以不用写ApiParam来描述接口参数。

数组的描述

@ApiOperation(value="删除用户-传递数组", notes="删除对象,传递数组")
@RequestMapping(value="/users/deleteByIds", method = RequestMethod.DELETE)
public void deleteUser(@ApiParam("用户ID数组") @RequestParam Integer[] ids) { (1)
for (int id:ids){
users.remove(id);
}
}

(1) 这里用ApiParam为数组参数添加描述

1.4 可选配置

在application.properties中加入以下配置,用于设置测试请求的host,默认在swagger ui上做请求测试时都是以/users/1为路径发送请求。
如果需要改变请求的根路径,就需要配置这个参数:
springfox.documentation.swagger.v2.host = yourapp.abc.com

配置获取api docs json数据的请求路径 ,默认为/v2/api-docs:
springfox.documentation.swagger.v2.path = /api

2. springfox-staticdocs 生成静态文档

springfox

2.1 Maven 配置

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-staticdocs</artifactId>
<version>2.2.2</version>
<scope>test</scope>
</dependency>

2.2 生成json文件

编写Junit测试,这样在测试环节就可以将api-docs的json数据写入文档,便于下一步生成asciidoc文件。

@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = DemoBootApplication.class)
public class Swagger2MarkupTest { @Autowired
private WebApplicationContext context; private MockMvc mockMvc; @Before
public void setUp() {
this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();
} @Test
public void createSpringfoxSwaggerJson() throws Exception {
String outputDir = "src/docs/json"; //将api-docs的json数据写入文件
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
.accept(MediaType.APPLICATION_JSON))
.andExpect(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);
}
}
}

2.3 配置Maven Plugin

配置以下两个插件:
swagger2markup-maven-plugin,该插件将json文件转为asciidoc
asciidoctor-maven-plugin, 该插件将asciidoc转为html/pdf

执行Maven命令 : mvn swagger2markup:convertSwagger2markup process-resources

生成的html文档存储在src\main\resources\META-INF\resources\docs目录下。
启动DemoBootApplication,直接访问http://localhost:8080/docs/index.html。

<pluginRepositories>
<pluginRepository>
<id>jcenter-snapshots</id>
<name>jcenter</name>
<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
</pluginRepository>
<pluginRepository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</pluginRepository>
</pluginRepositories> <build>
<plugins>
<!-- First, use the swagger2markup plugin to generate asciidoc -->
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>${swagger2markup.plugin.version}</version>
<dependencies>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-import-files-ext</artifactId>
<version>${swagger2markup.extension.version}</version>
</dependency>
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>${swagger2markup.version}</version>
</dependency>
</dependencies>
<configuration>
<!--The URL or file path to the Swagger specification-->
<swaggerInput>${swagger.input}</swaggerInput>
<outputDir>${generated.asciidoc.directory}</outputDir>
<config>
<!--设置输出文件的语言:ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP-->
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
<!--设置目录的展现方式-->
<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
<!--扩展Overview的内容,可以增加一些自定义的内容-->
<!--<swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
<swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
<swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
<swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security</swagger2markup.extensions.dynamicSecurity.contentPath>-->
</config>
</configuration>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>convertSwagger2markup</goal>
</goals>
</execution>
</executions>
</plugin> <!-- Run the generated asciidoc through Asciidoctor to generate
other documentation types, such as PDFs or HTML5 -->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<!-- Include Asciidoctor PDF for pdf generation -->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
<!-- Comment this section to use the default jruby artifact provided by the plugin -->
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>${jruby.version}</version>
</dependency>
<!-- Comment this section to use the default AsciidoctorJ artifact provided by the plugin -->
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
</dependencies>
<!-- Configure generic document generation settings -->
<configuration>
<!--默认指向 ${basedir}/src/main/asciidoc-->
<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
<!--an override to process a single source file; 默认指向 ${sourceDirectory} 中的所有文件-->
<!--<sourceDocumentName>index.adoc</sourceDocumentName>-->
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${generated.asciidoc.directory}</generated>
</attributes>
</configuration>
<!-- Since each execution can only handle one backend, run
separate executions for each desired output type -->
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
</configuration>
</execution> <!-- 生成PDF -->
<!--<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
</configuration>
</execution>--> </executions>
</plugin>
</plugins>
</build>

3. 其他说明

3.1 如何修改/v2/api-docs路径?

swagger-ui是通过获取接口的json数据渲染页面的,即通过swagger的注解将生成接口的描述服务,默认地址为/v2/api-docs,如果需要改变这个请求地址,可以在properties中配置springfox.documentation.swagger.v2.path。

3.2 如何设置所有请求的统一前缀?

默认请求都是以 / 根路径开始,如果我们的应用不是部署在根路径,比如以/platform部署,则可以通过一下方式设置请求的统一前缀。

@Bean
public Docket createV1RestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
.paths(PathSelectors.any())
.build()
.pathMapping("/platform"); // 在这里可以设置请求的统一前缀
}

3.3 接口文档中1.4和1.5的信息生成

接口文档中的 1.4和 1.5 则通过以下方式生成:
1.4 URI scheme
// 可以通过在properties中设置 springfox.documentation.swagger.v2.host属性
Host : localhost

// 待确认
BasePath : /

该Host也是swagger-ui发送测试请求的Host, 通常我们会将将接口文档部署在测试服务器,这样就需要设置Host,
否则请求都是通过localhost发送,请求不到测试服务器的接口。

1.5 Tags
@Api(value = "/v1/users",tags = "Users",description = "用户接口V1")
tags由Api注解的tags标签设置,如果不设置,则以类名作为tag

3.4 设置响应对象的Example

通过ApiModelProperty注解的example属性设置响应对象的示例:

@ApiModelProperty(value = "ID",example = "1")
private Integer id;
@ApiModelProperty(value = "姓名",example = "Admin")
private String name;
@ApiModelProperty(value = "地址",example = "171")
private String address;
@ApiModelProperty(value = "年龄",access = "hidden",example = "20")
private int age;
@ApiModelProperty(value = "性别",example = "1")
private int sex;
@ApiModelProperty(value = "生日",example = "2000-10-22")

链接

springfox文档

SpringBoot 整合 Swagger2的更多相关文章

  1. SpringBoot(七):SpringBoot整合Swagger2

    原文地址:https://blog.csdn.net/saytime/article/details/74937664 手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文 ...

  2. SpringBoot整合Swagger2

    相信各位在公司写API文档数量应该不少,当然如果你还处在自己一个人开发前后台的年代,当我没说,如今为了前后台更好的对接,还是为了以后交接方便,都有要求写API文档. 手写Api文档的几个痛点: 文档需 ...

  3. SpringBoot整合Swagger2(Demo示例)

    写在前面 由于公司项目采用前后端分离,维护接口文档基本上是必不可少的工作.一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理 ...

  4. springboot 整合Swagger2的使用

    Swagger2相较于传统Api文档的优点 手写Api文档的几个痛点: 文档需要更新的时候,需要再次发送一份给前端,也就是文档更新交流不及时. 接口返回结果不明确 不能直接在线测试接口,通常需要使用工 ...

  5. SpringBoot整合Swagger2案例,以及报错:java.lang.NumberFormatException: For input string: ""原因和解决办法

    原文链接:https://blog.csdn.net/weixin_43724369/article/details/89341949 SpringBoot整合Swagger2案例 先说SpringB ...

  6. SpringBoot整合Swagger2详细教程

    1. 简介   随着前后端分离开发模式越来越流行,编写接口文档变成了开发人员非常头疼的事.而Swagger是一个规范且完整的web框架,用于生成.描述.调用可视化的RESTful风格的在线接口文档,并 ...

  7. SpringBoot整合Swagger2及使用

    简介 swagger是一个流行的API开发框架,这个框架以"开放API声明"(OpenAPI Specification,OAS)为基础, 对整个API的开发周期都提供了相应的解决 ...

  8. SpringBoot整合Swagger2,再也不用维护接口文档了!

    前后端分离后,维护接口文档基本上是必不可少的工作.一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却很 ...

  9. SpringBoot学习笔记(16)----SpringBoot整合Swagger2

    Swagger 是一个规范和完整的框架,用于生成,描述,调用和可视化RESTful风格的web服务 http://swagger.io Springfox的前身是swagger-springmvc,是 ...

  10. Spring Boot2 系列教程(十七)SpringBoot 整合 Swagger2

    前后端分离后,维护接口文档基本上是必不可少的工作. 一个理想的状态是设计好后,接口文档发给前端和后端,大伙按照既定的规则各自开发,开发好了对接上了就可以上线了.当然这是一种非常理想的状态,实际开发中却 ...

随机推荐

  1. 用DirectDraw封装的位图动画类

    头文件 [cpp] view plaincopyprint? #pragma once #include <vector> using namespace std; #include &l ...

  2. 极限学习机︱R语言快速深度学习进行回归预测

    本文转载于张聪的博客,链接:https://ask.hellobi.com/blog/zason/4543. 深度学习在过去几年,由于卷积神经网络的特征提取能力让这个算法又火了一下,其实在很多年以前早 ...

  3. 如何使用DirectDraw直接显示RGB、YUV视频数据(播放yuv)

    #include "draw.h"void CTest100Dlg::OnButton1() { // TODO: Add your control notification ha ...

  4. 一些常用的api接口、

    taobao ip地址的api http://ip.taobao.com/service/getIpInfo.php?ip=IP 返回参数 code 状态码 data 数据信息 country 国家  ...

  5. R语言数据集合并、数据增减、不等长合并

    每每以为攀得众山小,可.每每又切实来到起点,大牛们,缓缓脚步来俺笔记葩分享一下吧,please~ --------------------------- 数据选取与简单操作: which 返回一个向量 ...

  6. AM335x(TQ335x)学习笔记——触摸屏驱动编写

    前面几篇文章已经通过配置DTS的方式完成了多个驱动的移植,接下来我们解决TQ335x的触摸驱动问题.由于种种原因,TQ335x的触摸屏驱动是以模块方式提供的,且Linux官方内核中也没有带该触摸屏的驱 ...

  7. (二十六)svn的问题二

    上周五请了一天假,电脑放在公司没有带回来,三天的时间都没有看代码,使得我电脑上的东西与svn上相差了太多,因为不一样,所以就要更新同步,因为要更新同步的东西多,便又出了一些问题,也因此对svn有了更进 ...

  8. ORA-00922:选项缺失或无效

    1.错误描述    ORA-00922:选项缺失或无效 2.错误原因 3.解决办法

  9. Exynos4412交叉编译环境搭建

    Exynos4412交叉编译环境搭建 交叉编译:在PC机(x86平台)上开发程序,在ARM板上运行,提高开发.编译速度. 环境: Tiny4412SDK1506开发板 需要软件: arm-linux- ...

  10. Django学习-16-Session

    1.保存在服务器的键值对           2.Session做验证时,还要依赖Cookie(重要).当用户登录成功时,生成随机字符串,一份放到Session,一份放到Cookie.当用户再次登录, ...