3

My team is working on a web application using Micro Service Architecture and Angular + Spring MVC. We follow Agile development. For each story, we create few implementation and test tasks. Documenting REST API is the first task to be done in the story.

We currently document it in Confluence so that developers and testers can work on implementation and test cases respectively.

We are looking to generate REST API documentation with Swagger automatically using codegen. It looks like documenting in Confluence and generating with Swagger is redundant. However, swagger generates accurate documentation.

What is the best way to document REST API before coding ? Are there any other tools ?

1

Why not to use Swagger in correlation with coding? The documentation is always in the current version, you don't need to maintain it, you can test it - a lot of benefits in this kind of approach. It is simple to integrate Swagger with Spring MVC. Start with the API (you don't need to implement anything)- so in Spring MVC it would be controllers layer and use it as a skeleton for your app. Here you have a config for Swagger using Docker - wrapper for swagger api.

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage(
                        "com.example.controllers"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "Info ...",
                "Info ...",
                "Version ...",
                "",
                new Contact("John Smith", "",
                        "john.smith@gmial.com"),
                "Copyright 2017 John Smith",
                "");
        return apiInfo;
    }

}

And two dependencies, assuming you use Maven

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0/version>
</dependency>

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

After building and deploying your app Swagger docs would be available

YOUR_SERVER:PORT/swagger-ui.html#/

And example usage in the controller

@ApiOperation(value = "Register user")
@RequestMapping(value = "/users", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ResponseStatus(HttpStatus.CREATED)
public void registerUser(@RequestBody @Valid NewUserRequest newUserRequest) {
    // you don't need to implement it now
}
  • We thought about this. If we add a new mandatory parameter or similar changes in REST API, test cases will fail until implementation – TechCrunch Mar 1 '17 at 12:13
  • "test cases will fail until implementation" which is good in my opinion; that is how it should work, shouldn't it? Failed test, implementation, test pass, refactor - like in TDD. – Tomasz Maciejewski Mar 1 '17 at 15:28
  • But they are not new tests so we can ignore. They will be existing tests and they can be broken by other changes and it can become a mess very soon. – TechCrunch Mar 1 '17 at 15:29
  • And IMHO it is still desirable approach. You should start development cycle with a new requirement. Then you write new acceptance test/change existing one. Here the development is starting. TDD preferable but can be wahtever fits you. When you start work on new featues/changes you should not be worried about failing tests. Simply make them pass. – Tomasz Maciejewski Mar 2 '17 at 11:05
2

Why don't you try the Swagger editor? It allows you to define the API in advance, and you can later replace that documentation with the automatically generated one, if you so desire, without changing its appearance too much.

Anyway, I recognize your problem, it's a bit of a pain to keep the Confluence documentation up to date. Could you possibly set up a continuous integration server to automatically update your Confluence whenever the source code is updated? For Jenkins, there's at least something called the Confluence Publisher Plugin. Confluence also has nice APIs so you could also create some script that the CI server runs and that updates the wiki in some completely custom fashion.

In any case you should have a link to the authoritative source, i.e. the Swagger-generated one, at the top of your Confluence page.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.