1)及时性 (接口变更后,能够及时准确地通知相关前后端开发人员)
2)规范性 (并且保证接口的规范性,如接口的地址,请求方式,参数及响应格式和错误信息)
3)一致性 (接口信息一致,不会出现因开发人员拿到的文档版本不一致,而出现分歧)
4)可测性 (直接在接口文档上进行测试,以方便理解业务)
1)添加pom.xml依赖
<pre class="md-fences md-end-block md-fences-with-lineno" lang="xml" contenteditable="false" cid="n252" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency></pre>
2)创建swagger配置文件
<pre class="md-fences md-end-block md-fences-with-lineno" lang="java" contenteditable="false" cid="n255" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
@Configuration
@EnableSwagger2
public class Swagger2Config {
}</pre>
3)启动程序
访问路径: http://localhost:8081/swagger-ui.html ,出现生成的文档页面。
此为原生界面,很难看,所以我们需要引入swagger-bootstrap-ui,也就是Knife4j的前身
4)使用Knife4j
a)添加pom.xml依赖
<pre class="md-fences md-end-block md-fences-with-lineno" lang="xml" contenteditable="false" cid="n268" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.7</version>
</dependency></pre>
b)开启Swagger2配置
<pre class="md-fences md-end-block md-fences-with-lineno" lang="java" contenteditable="false" cid="n271" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
import java.util.ArrayList
import java.util.List
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.apiInfo(apiInfo())
.select()
//swagger要扫描的包路径
.apis(RequestHandlerSelectors.basePackage("com.dsblog.server.controller"))
.paths(PathSelectors.any())
.build()
}
b)重启服务
访问地址: http://localhost:8081/doc.html ,这个ui界面看起来就更美观,更符合国人的使用习惯
1、添加pom.xml依赖
<pre class="md-fences md-end-block md-fences-with-lineno" lang="xml" contenteditable="false" cid="n282" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns=" http://maven.apache.org/POM/4.0.0 " xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance "
xsi:schemaLocation=" http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd ">
<modelVersion>4.0.0</modelVersion>
</project></pre>
2、创建Swagger2Config配置文件
<pre class="md-fences md-end-block md-fences-with-lineno" lang="java" contenteditable="false" cid="n285" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
package com.dsblog.server.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.*
import springfox.documentation.spi.DocumentationType
import springfox.documentation.spi.service.contexts.SecurityContext
import springfox.documentation.spring.web.plugins.Docket
import springfox.documentation.swagger2.annotations.EnableSwagger2
import java.util.ArrayList
import java.util.List
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.pathMapping("/")
.apiInfo(apiInfo())
.select()
//swagger要扫描的包路径
.apis(RequestHandlerSelectors.basePackage("com.dsblog.server.controller"))
.paths(PathSelectors.any())
.build()
.securityContexts(securityContexts())
.securitySchemes(securitySchemes())
}
}</pre>
3、创建SecurityConfig配置文件
<pre class="md-fences md-end-block md-fences-with-lineno" lang="java" contenteditable="false" cid="n288" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
package com.dsblog.server.config.security
import com.dsblog.server.model.User
import com.dsblog.server.service.IUserService
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.config.annotation.web.builders.WebSecurity
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter
import org.springframework.security.config.http.SessionCreationPolicy
import org.springframework.security.core.userdetails.UserDetailsService
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder
import org.springframework.security.crypto.password.PasswordEncoder
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter
@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
}</pre>
4、创建测试Controller,其中/login登录和/logout退出方法不需要Authorize验证,和上面的重写方法<mark style="box-sizing: border-boxbackground: rgb(255, 255, 0)color: rgb(0, 0, 0)">configure(WebSecurity web)</mark>匹配,user/info方法需要Authorize验证才能进行访问
<pre class="md-fences md-end-block md-fences-with-lineno" lang="java" contenteditable="false" cid="n291" mdtype="fences" style="box-sizing: border-boxoverflow: visiblefont-family: monospace, monospacefont-size: 0.9emwhite-space: predisplay: blockbreak-inside: avoidtext-align: leftbackground-image: background-position: var(--code-block-bg-color)background-size: background-repeat: var(--code-block-bg-color)background-attachment: background-origin: background-clip: background-color: rgb(248, 248, 248)position: relative !importantborder: 1px solid rgb(231, 234, 237)border-radius: 3pxpadding: 8px 4px 6px 0pxmargin-bottom: 15pxmargin-top: 15pxwidth: inheritcolor: rgb(51, 51, 51)font-style: normalfont-variant-ligatures: normalfont-variant-caps: normalfont-weight: normalletter-spacing: normalorphans: 2text-indent: 0pxtext-transform: nonewidows: 2word-spacing: 0px-webkit-text-stroke-width: 0pxtext-decoration-style: initialtext-decoration-color: initial">
package com.dsblog.server.controller
import com.dsblog.server.model.ResultBean
import com.dsblog.server.model.User
import com.dsblog.server.model.UserLoginParam
import com.dsblog.server.service.IUserService
import io.swagger.annotations.Api
import io.swagger.annotations.ApiOperation
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestBody
import org.springframework.web.bind.annotation.RestController
import javax.servlet.http.HttpServletRequest
import java.security.Principal
@Api(tags = "LoginController")
@RestController
public class LoginController {
}</pre>
5、重启程序,输入 http://localhost:8081/doc.html
6、测试
5)携带token发送到后台获取用户信息,验证通过
一份好的接口文档能够让接口调用者很清晰的知道如何调用一个API接口,包括请求方式、传参规范、接口返回信息等;也能帮助团队新人快速了解业务。
传统的做法是由开发人员维护一个API接口文档,一般是一个word文档或一个提供接口文档管理的网站。这种做法有很多弊端:文档难以维护、浪费开人员时间、文档难以与接口保持一致等。
Swagger2的出现很好的解决了上述问题,可以实现接口文档实时在线生成,提供在线接口测试功能。唯一的弊端就是对接口程序有侵入,但本人认为还是利大于弊的。
接下来我们将Swagger2整合到springboot项目中,并用swagger-bootstrap-ui对Swagger2进行界面美化,废话不多说,我们开始。。。
在pom.xml中导入
在application.yml中设置swagger2是否开启的开关,关闭后接口文档被关闭,在生产环境部署时就需要关闭接口文档。
1.创建注解SwaggerCustomIgnore.java,主要用于忽略某些不想生成接口文档的接口。
2.创建配置类SpringfoxSwagger2Config.java,配置Swagger接口文档生成规则和过滤规则。
3.拦截器排除swagger相关资源,新建或修改WebConfig.java文件,内容如下。
1.编写内容参考如下
2.注解说明
启动项目,浏览器输入http://location:8081/doc.html,效果如下。
第一种定义YAML文件,然后可以生成各种语言的代码框架,对于后台程序员来说,较少人会愿意写出一堆YAML格式。
第二种
swagger有各种语言的插件,可以通过配置及少量代码,生成接口文档及测试界面。
欢迎分享,转载请注明来源:内存溢出
评论列表(0条)