第05章—Swagger2打造在线接口文档

spring boot 系列学习记录：http://www.cnblogs.com/jinxiaohang/p/8111057.html

码云源码地址：https://gitee.com/jinxiaohang/springboot

一、添加Swagger2依赖

<dependency><!--添加Swagger依赖 -->

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.7.0</version>

</dependency>

<dependency><!--添加Swagger-UI依赖 -->

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.7.0</version>

</dependency>

二、添加配置

package com.xiaohang.springbootswagger2.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

 * 主要用途：开启在线接口文档和添加相关配置

 */

@Configuration //标记配置类

@EnableSwagger2 //开启在线接口文档

public class Swagger2Config {

    /**

     * 添加摘要信息(Docket)

     */

    @Bean

    public Docket controllerApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(new ApiInfoBuilder()

                        .title("标题：jzh_用户信息管理系统_接口文档")

                        .description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")

                        .contact(new Contact("jzh", null, "191041707@qq.com"))

                        .version("版本号:1.0")

                        .build())

                .select()

                .apis(RequestHandlerSelectors.basePackage("com.xiaohang.springbootswagger2.controller"))

                .paths(PathSelectors.any())

                .build();

    }

}

三、编写接口文档

@Api 描述类/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的参数
@ApiImplicitParams 描述方法的参数(Multi-Params)
@ApiIgnore 忽略某类/方法/参数的文档

参考链接：http://blog.csdn.net/hj95815/article/details/78323766

Swagger2 使用注解来编写文档，只需要在控制层（controller）添加注解来描述接口信息即可。例如：

@Api("用户信息管理")

@RestController

@RequestMapping("/api/user/*")

public class UserController {

    @Autowired

    private UserService userService;

    @ApiOperation("获取用户列表")

    @GetMapping("list")

    public List userList() {

        return userService.list();

    }

    @ApiOperation("获取单个用户")

    @ApiImplicitParam(paramType="query",name = "userId", value = "单个用户Id", dataType = "String")

    @GetMapping("list/{userId}")

    public User getOne(@RequestParam String userId){

        return userService.getOne(userId);

    }

    @ApiOperation("存储单个用户")

    @ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "json")

    @PostMapping(value = "save")

    public String save(@RequestBody User user) {

        if (userService.save(user))

            return user.toString();

        return "{\"msg\":\"error\"}";

    }

    @ApiOperation("更新单个用户")

    @ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "json")

    @PutMapping("update")

    public String update(@RequestBody User user) {

        if(userService.update(user))

            return user.toString();

        return "{\"msg\":\"error\"}";

    }

    @ApiOperation("删除单个用户")

    @ApiImplicitParam(paramType="query",name = "userId", value = "单个用户Id", dataType = "String")

    @DeleteMapping("delete/{userId}")

    public String delete(@RequestParam String userId) {

        if (userService.delete(userId))

            return "{\"msg\":\"success\"}";

        return "{\"msg\":\"error\"}";

    }

}

四、汉化(可跳过)

参考链接：https://www.jianshu.com/p/840320d431a1　　https://www.jianshu.com/p/7e543f0f0bd8

1、添加自定义页面

在resourece目录下创建\META-INF\resourece目录，然后创建一个名称为"swagger-ui.html" 的HTML文件。

内容如下：

<!DOCTYPE html>

<html>

<head>

    <meta charset="UTF-8">

    <title>Swagger UI</title>

    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>

    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>

    <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>

    <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

    <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

    <!--国际化操作：选择中文版 -->

    <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>

    <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

</head>

<body class="swagger-section">

<div id='header'>

    <div class="swagger-ui-wrap">

        <a id="logo" href="http://swagger.io">![](webjars/springfox-swagger-ui/images/logo_small.png)<span class="logo__title">swagger</span></a>

        <form id='api_selector'>

            <div class='input'>

                <select id="select_baseUrl" name="select_baseUrl"></select>

            </div>

            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>

            <div id='auth_container'></div>

            <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>

        </form>

    </div>

</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>

<div id="swagger-ui-container" class="swagger-ui-wrap"></div>

</body>

</html>

2、添加配置

package com.xiaohang.springbootswagger2.config;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;

import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration

class WebMvcConfig extends WebMvcConfigurerAdapter {

    @Override

    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("swagger-ui.html")

                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")

                .addResourceLocations("classpath:/META-INF/resources/webjars/");

    }

}

3、在启动类上添加注解@EnableWebMvc

五、查阅接口文档

打开 http://localhost:8080/swagger-ui.html

效果如下：

六、测试接口

更新中...

第05章—Swagger2打造在线接口文档的更多相关文章

SpringBoot 使用Swagger2打造在线接口文档（附汉化教程）
原文地址: https://www.jianshu.com/p/7e543f0f0bd8 SpringBoot + Swagger2 UI界面-汉化教程 1.默认的英文界面UI 想必很多小伙伴都曾经使 ...
spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档
文章目录一.Springfox 与 Swagger 简介 1.1 Springfox 1.2 Swagger 1.3 OpenApi.Swagger.Springfox的关系二.spring bo ...
springboot项目利用Swagger2生成在线接口文档
Swagger简介. Swagger2是一款restful接口文档在线生成和在线调试工具.很多项目团队利用Swagger自动生成接口文档,保证接口文档和代码同步更新.在线调试.简单地说,你可以利用这个 ...
使用swagger实现web api在线接口文档
一.前言通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址.参数.返回值.备注等等:像我们以前的做法是写在word/excel,通常是按模块划分,例如一个 ...
.NET Core WEB API使用Swagger生成在线接口文档
1项目引用Swashbuckle.AspNetCore程序集和Microsoft.Extensions.PlatformAbstractions程序集右击项目打开"管理NuGet程序包.. ...
使用swagger实现web api在线接口文档（转载）
一.前言通常我们的项目会包含许多对外的接口,这些接口都需要文档化,标准的接口描述文档需要描述接口的地址.参数.返回值.备注等等:像我们以前的做法是写在word/excel,通常是按模块划分,例如一个 ...
Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
net core Webapi基础工程搭建（三）——在线接口文档Swagger
目录前言 Swagger NuGet引用第三方类库别急,还有没错,注释小结前言前后分离的好处,就是后端埋头做业务逻辑功能,不需要过多考虑用户体验,只专注于数据.性能开发,对于前端需要的数据 ...
Spring Boot Swagger2自动生成接口文档
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 1.问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 2 ...

随机推荐

Mongodb更新数组$pull修饰符
http://blog.csdn.net/yaomingyang/article/details/78701643 一.$pull修饰符会删除掉数组中符合条件的元素,使用的格式是: { $pull: ...
Java并发编程（七）：线程安全策略
Java多线程——不可变对象 Java多线程——线程封闭 java线程不安全类与写法 Java线程安全同步容器 Java里的并发容器与安全共享策略总结
Springboot client 常用配置详解
Property name Description Default value spring.boot.admin.client.enabled Enables the Spring Boot Adm ...
详解Java中格式化日期的DateFormat与SimpleDateFormat类
DateFormat其本身是一个抽象类,SimpleDateFormat 类是DateFormat类的子类,一般情况下来讲DateFormat类很少会直接使用,而都使用SimpleDateFormat ...
Python学习之read()方法
read([size [,chars [,firstline]]]) 含义: 从文本流(io.TextIOWrapper)中解码数据并返回字符串对象.
什么是ETag
ETag 是 Entity Tag 的缩写,中文译过来就是实体标签的意思.在HTTP1.1协议中其实就是请求HEAD中的一个属性而已. HTTP/1.1 200 OK Date: Mon, 23 Ma ...
jQuery 实战读书笔记之第二章：选择元素
基本选择器 html 代码如下,后面的 js 使用的 html 基本大同小异. <!doctype html> <html> <head> <title> ...
angularjs 手动启动
谷歌推的javascript框架angulajs相当火热,由于新项目的缘故,最近一直看angularjs.在看的时候,一直有个疑问,angularjs 核心依赖于DI(依赖注入).常用的方法是在页面的 ...
[转]用了docker是否还有必要使用openstack?
从一项颠覆性的技术成果转化并衍生出一整套社区体系,Docker在发展速度上打破了一个又一个历史纪录.然而,Docker项目在采纳与普及方面表现出惊人态势的同时,也给我们带来了一系列疑问与困惑. 在今天 ...
sed awk文本处理教程
sed全名叫stream editor,流编辑器,用程序的方式来编辑文本,相当的hacker啊.sed基本上就是玩正则模式匹配,所以,玩sed的人,正则表达式一般都比较强. 把my字符串替换成Hao ...

第05章—Swagger2打造在线接口文档

一、添加Swagger2依赖

二、添加配置

三、编写接口文档

四、汉化(可跳过)

五、查阅接口文档

六、测试接口

第05章—Swagger2打造在线接口文档的更多相关文章

随机推荐

热门专题