为了账号安全,请及时绑定邮箱和手机立即绑定

Swagger使用

标签:
SpringBoot

Swagger学习及生成HTML文档

Swagger

1、集成springboot

第一步:pom

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

第二步:swagger在springboot中配置

属性类(省略get/set方法)

/**
 * swagger配置,生成api
 *
 * @author lirui
 * @date 2018-07-26
 */@ConfigurationProperties(prefix = "hyboot.api")public class HySwaggerProperties {    /**
     * 是否开启swagger
     */
    private boolean enabled = false;    /**
     * API服务标题
     */
    private String title;    /**
     * API服务描述
     */
    private String description;    /**
     * API服务版本
     */
    private String version;    /**
     * Api负责人相关信息
     */
    private Leader leader = new Leader();    public static class Leader{        /**
         * 负责人姓名
         */
        private String name;        /**
         * 负责人邮箱
         */
        private String email;
    }    /**
     * 用于生成api的html静态文档,需要配置
     */
    private Swagger swagger = new Swagger();    public static class Swagger{        /**
         * api 接口获取数据地址
         */
        private String apiUrl;        /**
         * 生成文件的位置
         */
        private String filePath;
    }
}

配置application.yml

 enabled: false title: 测试服务api description: 用于测试 leader:   name: 汤姆   email: tom@163.com version: 1.0.0

配置类

/**
 * swagger配置,生成api
 *
 * @author lirui
 * @date 2018-07-26
 */@Configuration@EnableConfigurationProperties({HySwaggerProperties.class})@EnableSwagger2public class HySwaggerAutoConfiguration {

    private Logger logger = LoggerFactory.getLogger(HySwaggerAutoConfiguration.class);    @Autowired
    private ApplicationContext applicationContext;    
    @Autowired
    private HySwaggerProperties hySwaggerProperties;    
    @Autowired
    private ServerProperties serverProperties;    /**
     * 定义api生成规则
     *
     * @return
     */
    @Bean
    public Docket hyApi() {        return new Docket(DocumentationType.SWAGGER_2)                  //group为系统编号(我们spring的id设置为了系统编号)
                .groupName(applicationContext.getId())
                .apiInfo(apiInfo())                //支持协议
                .protocols(Set.of("http", "https"))
                .select()                 //限制只有在类上加@Api才添加到swagger,默认是都添加的
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))                 //限制只有在方法上加@Api才添加到swagger,默认是都添加的
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }    /**
     * api相关信息
     *
     * @return
     */
    public ApiInfo apiInfo() {        return new ApiInfoBuilder()                //服务标题
                .title(hySwaggerProperties.getTitle() == null ?
                    applicationContext.getId() + "系统服务API" :                                                   hySwaggerProperties.getTitle())                //api服务描述
                .description(hySwaggerProperties.getDescription())                //api版本
                .version(hySwaggerProperties.getVersion())                //联系人
                .contact(                        new Contact(hySwaggerProperties.getLeader().getName(), "",
                                hySwaggerProperties.getLeader().getEmail()))
                .build();
    }
}

第三步:访问

http://host:port/contentPath/swagger-ui.html

https://img1.sycdn.imooc.com//5b5b17bd0001b2f015550678.jpg

2、生成adoc文件,便于生成HTML/PDF

主要想法是:Swagger2MarkupConverter(可以根据指定url生成adoc文件,用于生成html),如果想调用当前系统生成adoc文件,就必须保证系统启动完成,这样才能根据url访问

第一步:定义生成adoc文件的类

springboot中提供了ApplicationRunner,这个保证了系统启动完执行其中的run方法,所以只要在run方法中调用Swagger2MarkupConverter#from

/**
 * 系统运行完执行,用于swagger生成adoc文件,继而产生api接口Html静态文件
 * 必须是spring管理的Bean才生效
 * @author lirui
 * @date 2018-07-26
 */public class SwaggerCreatAdocRunner implements ApplicationRunner {    /**
     * api 接口获取数据地址
     */
    private String apiUrl;    /**
     * 生成文件的位置
     */
    private String filePath;    @Override
    public void run(ApplicationArguments args) throws Exception {        try {            //从指定地址获取数据生成接口文档
            Swagger2MarkupConverter.from(new URL(apiUrl)).build()
                    .toFile(Paths.get(filePath));

        } catch (MalformedURLException e) {
            e.printStackTrace();
        }
    }    public String getApiUrl() {        return apiUrl;
    }    public void setApiUrl(String apiUrl) {        this.apiUrl = apiUrl;
    }    public String getFilePath() {        return filePath;
    }    public void setFilePath(String filePath) {        this.filePath = filePath;
    }
}

第二步:swagger配置初始化SwaggerCreatAdocRunner

就是在上述HySwaggerAutoConfiguration增加了一个SwaggerCreatAdocRunnerspring的bean定义

(添加了默认不开启Swagger的配置)

/**
 * swagger配置,生成api
 *
 * @author lirui
 * @date 2018-07-26
 */@Configuration@EnableConfigurationProperties({HySwaggerProperties.class, ServerProperties.class})@EnableSwagger2@ConditionalOnExpression("${hyboot.api.enabled:false}")public class HySwaggerAutoConfiguration {

    private Logger logger = LoggerFactory.getLogger(HySwaggerAutoConfiguration.class);    public static final String LOCALHOST = "127.0.0.1";    @Autowired
    private ApplicationContext applicationContext;    @Autowired
    private HySwaggerProperties hySwaggerProperties;    @Autowired
    private ServerProperties serverProperties;        /**
     * 定义api生成规则
     *
     * @return
     */
    @Bean
    public Docket hyApi() {
        ...
    }    /**
     * 用于生成swagger API html文档
     * http://localhost:8081/demo/v2/api-docs?group=hyboot-demo
     *
     * @return
     */
    @Bean
    public SwaggerCreatAdocRunner swaggerRunner() {        //生成api文档的数据来源
        String apiUrl = hySwaggerProperties.getSwagger().getApiUrl();
        String filePath = ClassLoader.getSystemResource("").getPath()+"api";        //解决window系统路径前带"/"问题
        File file = new File(filePath);
        filePath = file.getPath();        //设置swagger生成adoc文件启动类
        SwaggerCreatAdocRunner swaggerCreatAdocRunner = new SwaggerCreatAdocRunner();
        swaggerCreatAdocRunner.setApiUrl(apiUrl);
        swaggerCreatAdocRunner.setFilePath(filePath);        if (StringUtils.isBlank(apiUrl)) {            //端口
            int port = serverProperties.getPort();            //项目
            String contextPath = serverProperties.getServlet().getContextPath();

            String group = applicationContext.getId();
            apiUrl = "http://" + LOCALHOST + ":" + port + contextPath + "/v2/api-docs?group=" + group;

            swaggerCreatAdocRunner.setApiUrl(apiUrl);
        }        return swaggerCreatAdocRunner;
    }    /**
     * api相关信息
     *
     * @return
     */
    public ApiInfo apiInfo() {
        ...
    }
}

第三步:利用上诉生成的adoc文件生成HTML静态文件

这里要用到maven的插件asciidoctor

 <!--增加swagger生成html-->
 <plugin>
   <groupId>org.asciidoctor</groupId>
   <artifactId>asciidoctor-maven-plugin</artifactId>
   <version>1.5.6</version>
   <configuration>
     <sourceDirectory>${project.basedir}/target/classes/</sourceDirectory>
     <sourceDocumentName>api.adoc</sourceDocumentName>
     <outputFile>${project.basedir}/target/classes/api.html</outputFile>
     <backend>html</backend>
     <sourceHighlighter>coderay</sourceHighlighter>
     <attributes>
       <toc>left</toc>
     </attributes>
   </configuration>
 </plugin>

执行mvn asciidoctor:process-asciidoc

在IDEA中直接点击如图即可:
https://img1.sycdn.imooc.com//5b5b17cd00018ae205080154.jpg

生成的HTML静态文件
https://img1.sycdn.imooc.com//5b5b17db000116f415350683.jpg

原文出处:http://www.cnblogs.com/liruiloveparents/p/9378327.html

点击查看更多内容
2人点赞

若觉得本文不错,就分享一下吧!

评论

作者其他优质文章

正在加载中
感谢您的支持,我会继续努力的~
扫码打赏,你说多少就多少
赞赏金额会直接到老师账户
支付方式
打开微信扫一扫,即可进行扫码打赏哦
今天注册有机会得

100积分直接送

付费专栏免费学

大额优惠券免费领

立即参与 放弃机会
意见反馈 帮助中心 APP下载
官方微信

举报

0/150
提交
取消